---
title: "One rule in full: what it checks, why, how to fix it, how a fix is verified"
method: GET
path: "/v1/rules/{rule}"
tags: ["rules"]
---

# One rule in full: what it checks, why, how to fix it, how a fix is verified

`GET /v1/rules/{rule}`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/rules/{rule}`
- Auth: HTTP bearer

One rule from the catalogue, in full: what it checks (`predicate`), the URLs and gates it applies to, its thresholds with defaults, citations, where Frontshelf deliberately differs from a widely used desktop SEO crawler (`delta_from_sf`), and how a fix is verified (`verification_mode`: `http_probe` re-fetches the affected pages live, `full_crawl` waits for the next committed crawl; only the verifier resolves an issue). Name it by catalogue id, desktop-crawler filter key or filter-key id; NOT_FOUND means no such rule, and rules_list names them. With `site`, a rule whose name carries a number is named with that site's threshold. Next: pages_list with `site` and the rule's id as `filter` for the pages it fired on.

## Path parameters

- `rule` string, required: A rule by catalogue id (metadata.missing_title), its desktop-crawler filter key (TITLE_MISSING, any case) or its filter-key id (37).

## Query parameters

- `site` string: Optional: name a site and the rule's name and `threshold` carry its value.

## Response `200`

One rule in full: what it checks, why, how to fix it, how a fix is verified

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `rule` object, required: The rule in full.
    - `id` string, required: The catalogue id every other door names the rule by.
    - `sf_key` string, nullable, required: The desktop-crawler filter key; null for Frontshelf's own rules.
    - `tab` string, required: The Explorer tab the rule sits on, in id form (page_titles); filters_list names every tab.
    - `tab_label` string, required: The tab as the Explorer shows it (Page Titles).
    - `name` string, required: The rule's name; a number in it is the threshold `threshold` describes.
    - `type` 'issue' | 'warning' | 'opportunity', required: The classification a widely used desktop SEO crawler gives the rule, kept as is: an issue is a defect, a warning needs a look.
    - `priority` 'high' | 'medium' | 'low', required: The priority a widely used desktop SEO crawler gives the rule. With `type`, it sets the rule's weight in the health score.
    - `severity` 'critical' | 'high' | 'medium' | 'low' | 'info', required: The severity an issue of this rule carries, derived from `type` and `priority` unless the rule overrides it.
    - `stage` 'page' | 'analysis' | 'integration', required: `page`: judged on one page; `analysis`: across the crawl; `integration`: from a connected service.
    - `needs` string[], required: What judging it takes beyond a fetch (render, axe, lighthouse, ...).
    - `filter_key_id` integer, required: The frozen number a page filter takes for this rule.
    - `implemented` boolean, required: False: catalogued and documented, not yet judging crawls.
    - `hint` string, required: What the rule finds, in one line.
    - `description` string, required: What the rule finds and why it matters, in full.
    - `tip` string, required: How to fix it.
    - `threshold` object, nullable, required: The threshold the rule's name carries; null for a rule whose name carries no number.
      - `key` string, required
      - `value` number, required: The value the name says, in the catalogue's stored unit.
      - `default` number, required
      - `unit` string, required
      - `source` 'site' | 'default', required: `site`: this site's value differs from the catalogue default.
    - `url_set` string, required: The URLs the rule applies to.
    - `gate` string[], required: The conditions a URL must meet first.
    - `thresholds` object[], required: Every setting the rule reads, with its default and the range a site may set it to.
      - `key` string, required
      - `default` number, required
      - `min` number, required
      - `max` number, required
      - `unit` string, required
    - `predicate` string, required: What the rule checks, in the spec's words.
    - `citations` string[], required: The sources the rule rests on (search engine documentation, standards), as URLs.
    - `delta_from_sf` string, nullable, required: Where Frontshelf deliberately differs from a widely used desktop SEO crawler; null when it does not.
    - `verification_mode` 'http_probe' | 'full_crawl', nullable, required: How the verifier checks a fix, in the words verifications_start and verifications_get answer: `http_probe` re-fetches the affected pages live after the rule's settle time; `full_crawl` waits for the next committed crawl. An issue with more affected URLs than one probe can check is verified by crawl anyway. Null only for the engine's own sentinel, which is never an issue. Only the verifier resolves an issue.
    - `engine` boolean, required: The engine's own sentinel: never an issue, never scored.
    - `mcp_description` string, required: The rule in one paragraph, written for an agent.

## Other responses

- `400`: VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: NOT_FOUND, SITE_NOT_FOUND
- `409`: AMBIGUOUS_SITE, AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

[API](https://skmtc.dev/frontshelf/apis/frontshelf-api.md) · [All operations](https://skmtc.dev/frontshelf/apis/frontshelf-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontshelf/apis/frontshelf-api/revisions/ce3602d26c7c?raw)