---
title: "List the rule catalogue: every check Frontshelf judges by"
method: GET
path: "/v1/rules"
tags: ["rules"]
---

# List the rule catalogue: every check Frontshelf judges by

`GET /v1/rules`

## Request

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

The rule catalogue: every check Frontshelf can judge a page or a crawl by (the issues a widely used desktop SEO crawler reports, plus Frontshelf's own), each with its tab, type, priority, severity, stage, what it needs, a description and a fix tip. Product data, no crawled content. `implemented: false` means the rule is catalogued but not yet judging crawls. Pass `tab` to narrow. With `site`, the rules whose name carries a number are named with that site's thresholds, and `threshold` says the value, the catalogue default and which is in force; without it, the catalogue defaults. Pages with `cursor`; a cut list says so in `truncation`. Next: rules_get for one rule's predicate, citations and how a fix is verified.

## Query parameters

- `tab` string: One of the Explorer's tabs in its id form (page_titles, h1, canonicals, accessibility, frontshelf, ...); filters_list names them all.
- `site` string: Optional: name a site and the rule names carry its thresholds.
- `limit` integer: Items per page (1 to 100).
- `cursor` string: The continuation from a previous page's page_info.next_cursor. Never construct one.

## Response `200`

List the rule catalogue: every check Frontshelf judges by

- 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.
  - `items` object[], required: The rules on this page, in catalogue order.
    - `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.
  - `truncated` boolean, required: True when more rules exist than this page shows.
  - `total` integer, required: Rules matching, on every page together.
  - `truncation` object, required: Whether the list was cut, and the call that reads the rest.
    - `truncated` boolean, required: True when more match than this answer holds.
    - `omitted_count` integer, required: Rows this answer knows it left out; 0 on a keyset page, which cannot count them (read `total`).
    - `reason` string: Why the list was cut (`page_limit`).
    - `continue_with` object: The call that reads the next page, arguments complete.
      - `capability` string, required
      - `arguments` object, required
  - `page_info` object, required: Where this page sits in the whole list.
    - `has_more` boolean, required: True when another page follows.
    - `next_cursor` string, nullable, required: Pass it back as `cursor` for the next page; null at the end.
    - `estimated_total` integer, required: How many match in all, after the filters; not the rows of this page.

## Other responses

- `400`: INVALID_FILTER, INVALID_CURSOR, VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `403`: SCOPE_DENIED
- `404`: 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)