Bot Appétit

Explain one Bot Appétit check: what it looks at, why it matters for machines reading a page, and what good looks like. Use the id from list_checks or a report. Costs nothing and does not scan.

Get a stored Bot Appétit report by scan id, the same report a person sees at botappetit.ai/r/<id>. Costs nothing and does not scan. Use it to re-read a report you were given a link to. A page that blocked our scanner is returned as blocked, with no score.

The highest-scoring sites by category, from the latest Bot Appétit scan of each site's homepage: rank, host, score out of 100, grade and a link to the full report. Call it with no category to see the top of every category, or with a category id for that board. Only sites that were scored on the current rules are ranked; a site that blocked our scanner is never ranked.

List every check Bot Appétit runs on a page, grouped by category, with the id of each. Use the id with explain_check for what a check means and what good looks like. Every check asks one question: can a machine consume this page?

List the sites the signed-in person follows in Bot Appétit, newest activity first, each with its latest site-scan score, the change since the scan before, and the trend. Use a host from here with site_history, set_pins and the other site tools.

List every stored Bot Appétit scan of one exact page, newest first, with the score at the time and how it moved since the scan before. Costs nothing and does not scan. Use it to show whether a page has improved. Blocked and failed scans are listed without a score.

A whole-site scan reads a representative sample of a site and needs a person with a Bot Appétit account, and an agent never creates one. This returns exactly what the person must do, in order: connect this agent to their account (a one-time approval in their browser), after which start_site_scan, site_scan_status, list_sites and the other account tools work. For a single page, use scan_page instead, which is free and needs no account.

Check one web page for AEO, SEO and performance: can a machine consume it? Returns the findings by check and the report link. If the exact page was scanned in the last 24 hours the stored result is returned at no cost; set fresh to scan again. A page that blocks our scanner is returned as blocked with no score, because it cannot pass. Free, no account needed.

Pin or unpin pages on one of the signed-in person's sites. Pinned pages are scanned in every site scan of that site and count toward its score; up to 25, on the site itself. Give pin and/or unpin lists. Returns each address's outcome and the pins now in place; they apply from the next scan.

Turn the signed-in person's monthly re-scans of their sites on or off, and the email of each result on or off. Leave a field out to keep it as it is; call with no fields to read the current settings. The settings belong to the account, not to one site.

Create or stop the unlisted share link for one of the signed-in person's site scans. Site scans are private by default; a link lets anyone who holds it read that one scan (not the person's other scans) and stays valid until stopped. Only create a link when the person has asked to share the scan, and tell them who can open it.

Read one of the signed-in person's sites over time: every site scan of it newest first with the score and the change since the previous scored scan (a change across a scoring update or different pinned pages is marked, not passed off as the site's own), the pinned pages, and the monthly re-scan settings.

Read one of the signed-in person's site scans: whether it is still running, and once it has finished the score, the checks that failed, the category scores and the pages it covered, each page with a link to its own full report. Only the account that ran the scan can read it. A scan that is still running is normal, not an error. A full scan of a large site usually takes about 2 and a half minutes and nine in ten finish within about 5 and a half minutes; a site of ten pages or fewer usually finishes in under half a minute. Do not poll: the first answer asks for one check after 30 seconds, and if the scan is still running the next answer says how long to wait. Read check_again_after_seconds in the answer and wait that long before the next check.

Start a whole-site scan for the signed-in person's account: Bot Appétit reads a representative sample of the site (not every page) and scores it. Needs the person to have authorised this connection. It returns a job_id straight away and the scan runs in the background, so read it with site_scan_status. A full scan of a large site usually takes about 2 and a half minutes and nine in ten finish within about 5 and a half minutes; a site of ten pages or fewer usually finishes in under half a minute. Do not poll: the first answer asks for one check after 30 seconds, and if the scan is still running the next answer says how long to wait. Read check_again_after_seconds in the answer and wait that long before the next check. The result is private to their account until they choose to share it. For one page, use scan_page, which needs no account.