---
title: "Public API"
description: "Search the Good for Bots directory, read published website reports and discover the current scoring methodology through our public JSON API."
url: "https://goodforbots.com/api"
---

# Read Good for Bots through the API.

Search the Good for Bots directory, read published website reports and discover the current scoring methodology through our public JSON API.

These reads require no account or API key. Every endpoint returns JSON. Reading a report never starts a scan.

[OpenAPI description](https://goodforbots.com/api/openapi.json) · [API catalog](https://goodforbots.com/.well-known/api-catalog)

## Make your first request

Use GET with `Accept: application/json`. These examples read live public data:

### Search the directory

```sh
curl -H 'Accept: application/json' 'https://goodforbots.com/api/sites?q=example&limit=5'
```

### Discover available filters

```sh
curl -H 'Accept: application/json' 'https://goodforbots.com/api/sites/facets'
```

### Read the current methodology

```sh
curl -H 'Accept: application/json' 'https://goodforbots.com/api/standards'
```

Pick a `host` from the directory response, then request `/api/sites/{host}/report`. The report supplies findings, available fix prompts and links to its human-readable and Markdown versions.

## Available reads

### Search published listings

```text
GET /api/sites
```

Returns published directory entries. Removed, deleted, blocked, opted-out and redirected listings are excluded. Filters combine with AND; repeated category, tag, platform and band values use OR, while capabilities use AND. Unknown well-formed slugs return no matches. Results may change between pages when a scan is published; an out-of-range page returns an empty data array with the real total.

- `q`: Case-insensitive literal substring of host, name or tagline. Whitespace is trimmed.
- `category`: Active category slug from /api/categories. Repeat for OR.
- `tag`: Active tag slug from /api/tags. Repeat for OR.
- `platform`: Platform slug from /api/sites/facets. Repeat for OR.
- `capability`: Passed check ID from /api/sites/facets. Repeat for AND: every specified check must pass.
- `band`: Band ID from /api/standards data.rubric.bands. Repeat for OR.
- `status`: Listing ownership status.
- `minScore`: Minimum score, inclusive. Must not exceed maxScore.
- `maxScore`: Maximum score, inclusive.
- `sort`: Result order; paid plans never change ranking.
- `page`: Page number.
- `limit`: Entries per page.

### Find existing reports by name or domain

```text
GET /api/sites/suggestions
```

Returns up to five published catalogue identities: host, name and logoUrl. Matches literal host or name text, ignoring case. Exact host matches come first, then exact names, prefixes and substrings; ties use host order. Scores and payments do not affect ranking. The same visibility rules as the directory apply. Reading suggestions never starts a scan.

- `q` (required): Name or canonical domain fragment. Whitespace is trimmed; wildcard characters are literal.

### Discover filters and counts

```text
GET /api/sites/facets
```

Accepts listing filters, but no sort, page or limit. Category counts ignore the selected category; platform counts ignore the selected platform. Signal counts keep every current filter and add the candidate signal. Counts describe listings, not the whole web.

- `q`: Case-insensitive literal substring of host, name or tagline. Whitespace is trimmed.
- `category`: Active category slug from /api/categories. Repeat for OR.
- `tag`: Active tag slug from /api/tags. Repeat for OR.
- `platform`: Platform slug from /api/sites/facets. Repeat for OR.
- `capability`: Passed check ID from /api/sites/facets. Repeat for AND: every specified check must pass.
- `band`: Band ID from /api/standards data.rubric.bands. Repeat for OR.
- `status`: Listing ownership status.
- `minScore`: Minimum score, inclusive. Must not exceed maxScore.
- `maxScore`: Maximum score, inclusive.

### Read a published report

```text
GET /api/sites/{host}/report
```

Reads an existing report without starting a scan. Use a canonical host from /api/sites: lowercase ASCII/punycode, without scheme, path, port, leading www or trailing dot. Blocked, opted-out and redirected reports can be read by host and have no score. Prompt visibility and historical access follow the listing's plan, independent of the caller. Missing, removed, deleted and never-published listings return 404.

- `host` (required): Canonical hostname, for example example.com.
- `scan`: Published scan ID belonging to this site. Omit for the latest report. A historical scan requires the listing's history entitlement.

### Check report generation status

```text
GET /api/sites/{host}/enrichment
```

Reads the current published scan's description and file-generation states without starting work. Poll only while queued, generating or delayed; pause when hidden or offline and back off on errors. An opaque revision changes when content or its status changes. Delayed work has an earliest retry time, not a completion estimate. Files are null without entitlement; the entire result is null for unscored reports. No model, error details, costs or internal job identifiers are exposed. Unknown queries are rejected.

- `host` (required): Canonical hostname.

### Read the current scoring methodology

```text
GET /api/standards
```

Current rubric, score bands, public check descriptions and the AI crawler registry. Historical reports retain their own scoring version. Read band IDs and labels here instead of hardcoding them. Capabilities and experimental checks do not add points.

### List active categories

```text
GET /api/categories
```

Active categories, including empty ones, ordered by order then slug. Use slug as the category filter.

### List active industry tags

```text
GET /api/tags
```

Active tags, including unused ones, ordered by order then slug. Use slug as the tag filter.

## Read responses and handle failures

Successful responses wrap their result in `data`. Directory results also include `pagination`: page, limit, total and totalPages. The default page size is 24, the maximum is 100, and pages start at 1. Response objects may gain fields; ignore fields your client does not use.

Listing filters and report reads reject unknown query parameters and repeated scalar parameters with HTTP 400. Filters return no matches for unknown, well-formed slugs. Category, tag and standards reads take no parameters; additional query parameters are ignored.

A missing report returns 404. Historical reports can return 403 when the listing’s plan does not include history. Public access does not change how many fix prompts that listing exposes. Blocked, opted-out and redirected (`moved`) reports have no score; null never means zero.

JSON errors include an `error` message and may include validation `issues`. HTTP 502 or 503 means a temporary service problem; retry with backoff. Use bounded pages and avoid tight polling. Catalogue reads may reuse data for up to a minute; removals invalidate that cache.

The [OpenAPI description](https://goodforbots.com/api/openapi.json) defines parameter limits and response fields. Use the [methodology](https://goodforbots.com/standards) to interpret scores. Questions or integration problems? [Contact us](https://goodforbots.com/contact).

## Structured data

```json
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebPage",
      "@id": "https://goodforbots.com/api#webpage",
      "url": "https://goodforbots.com/api",
      "name": "Public API",
      "description": "Search the Good for Bots directory, read published website reports and discover the current scoring methodology through our public JSON API.",
      "inLanguage": "en",
      "isPartOf": {
        "@id": "https://goodforbots.com/#website"
      },
      "breadcrumb": {
        "@id": "https://goodforbots.com/api#breadcrumb"
      }
    },
    {
      "@type": "BreadcrumbList",
      "@id": "https://goodforbots.com/api#breadcrumb",
      "itemListElement": [
        {
          "@type": "ListItem",
          "position": 1,
          "name": "Home",
          "item": "https://goodforbots.com/"
        },
        {
          "@type": "ListItem",
          "position": 2,
          "name": "Public API",
          "item": "https://goodforbots.com/api"
        }
      ]
    },
    {
      "@type": "Organization",
      "@id": "https://goodforbots.com/#organization",
      "name": "Good for Bots",
      "url": "https://goodforbots.com",
      "logo": "https://goodforbots.com/icon-512.png",
      "founder": {
        "@id": "https://goodforbots.com/#person-mateusz-pawlica"
      },
      "contactPoint": {
        "@type": "ContactPoint",
        "contactType": "customer support",
        "email": "support@goodforbots.com",
        "url": "https://goodforbots.com/contact"
      }
    },
    {
      "@type": "WebSite",
      "@id": "https://goodforbots.com/#website",
      "name": "Good for Bots",
      "url": "https://goodforbots.com",
      "description": "Check if AI crawlers can access and read your website, free. Get a score out of 100 with every finding and fix prompts, then browse reports in the directory.",
      "inLanguage": "en",
      "publisher": {
        "@id": "https://goodforbots.com/#organization"
      },
      "potentialAction": {
        "@type": "SearchAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "https://goodforbots.com/directory?q={q}"
        },
        "query-input": "required maxlength=120 name=q"
      }
    },
    {
      "@type": "Person",
      "@id": "https://goodforbots.com/#person-mateusz-pawlica",
      "name": "Mateusz Pawlica",
      "givenName": "Mateusz",
      "familyName": "Pawlica",
      "jobTitle": "Founder of Good for Bots",
      "description": "Web developer who builds directories and AI-powered products, and the founder of Good for Bots.",
      "url": "https://goodforbots.com/about#founder",
      "sameAs": [
        "https://pl.linkedin.com/in/mateusz-pawlica-65238816b",
        "https://pawlicaweb.pl/o-mnie"
      ],
      "knowsAbout": [
        "llms.txt",
        "robots.txt",
        "AI crawlers",
        "Markdown content negotiation",
        "Structured data",
        "Technical SEO",
        "Web directories",
        "Next.js",
        "TypeScript",
        "Generative AI"
      ],
      "worksFor": {
        "@id": "https://goodforbots.com/#organization"
      }
    }
  ]
}
```