therankingfactory-com Public API

openapi: 3.2.0
info:
  title: Ranking Factory free site check Public API
  version: 1.0.0
  summary: Checks one public website's readiness for AI search. Free, no account, no key.
  description: 'The same fetch-only check as https://therankingfactory.com/audit and the check_site tool of the MCP server at https://therankingfactory.com/api/mcp/check: whether AI crawlers may read the site, whether its pages can be read without JavaScript, its structured data, titles and llms.txt. It asks no AI engine and stores nothing. This is the only public REST API we offer; everything else is reached through MCP (https://therankingfactory.com/developers).'
  contact:
    name: The Ranking Factory
    email: support@therankingfactory.com
    url: https://therankingfactory.com/developers
  termsOfService: https://therankingfactory.com/terms
servers:
- url: https://therankingfactory.com
security: []
tags:
- name: Public
paths:
  /api/public/site-check:
    get:
      operationId: checkSite
      summary: Check one website for AI search readiness
      description: 'Fetches the site the way a search engine and an AI crawler would and answers with each finding''s title and tier (Blocker first), every check made with its result, and fullReport: where the person can have the full report emailed. 60 checks an hour are answered in all, shared with the check_site MCP tool, and one site can be checked 20 times a day.'
      parameters:
      - name: url
        in: query
        required: true
        description: The site's address, e.g. example.com or https://www.example.com/. Without a scheme, https is assumed.
        schema:
          type: string
          minLength: 1
          maxLength: 2048
        example: example.com
      responses:
        '200':
          description: What the check found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SiteCheckResult'
        '400':
          description: No address, an address that is not a public http(s) website, or one that leads to a private network.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 'Too many checks: the hour''s allowance for everyone, or this site''s for the day. Retry-After says when to ask again.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              description: Seconds to wait before asking again.
              schema:
                type: integer
                minimum: 1
        '502':
          description: The check could not be completed. Nothing is wrong with the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Public
components:
  schemas:
    Check:
      type: object
      description: One check made.
      required:
      - group
      - name
      - result
      properties:
        group:
          type: string
          description: Which question it answers.
          enum:
          - Can AI reach the page
          - Can AI read it
          - Does it say who you are
          - Is it ready for AI agents
          - Does AI name and cite you
          - What this check does not measure
        name:
          type: string
          description: The check.
        result:
          type: string
          description: What happened.
          enum:
          - Passed
          - Problem
          - Missing
          - NotChecked
          - NotMeasured
          - Info
          - NotOffered
      additionalProperties: false
    Scores:
      type: object
      description: Each 0-100, or null when the audit behind it could not read the page.
      required:
      - seo
      - geo
      - agentReadiness
      properties:
        seo:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        geo:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        agentReadiness:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
      additionalProperties: false
    SiteCheckResult:
      type: object
      description: What one check found. Titles and tiers only; the working is in the emailed report.
      required:
      - site
      - checkedAt
      - scores
      - findings
      - checks
      - fullReport
      - note
      properties:
        site:
          type: string
          description: The address that was checked, after redirects.
        checkedAt:
          type: string
          format: date-time
          description: When the check ran, UTC.
        scores:
          $ref: '#/components/schemas/Scores'
        findings:
          type: array
          description: What it found, most urgent first.
          items:
            $ref: '#/components/schemas/Finding'
        checks:
          type: array
          description: Every check made, passed included.
          items:
            $ref: '#/components/schemas/Check'
        fullReport:
          type: string
          format: uri
          description: Where the person can have the full report emailed, free.
        note:
          type: string
          description: What this answer does and does not cover.
      additionalProperties: false
    Error:
      type: object
      description: 'A refusal: a code to branch on and a sentence for the person.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: What was refused.
          enum:
          - url_required
          - invalid_url
          - address_refused
          - busy
          - site_limit
          - check_failed
        message:
          type: string
          description: Why, and what would be accepted.
      additionalProperties: false
    Finding:
      type: object
      description: One finding.
      required:
      - tier
      - title
      - locked
      - lockedReason
      properties:
        tier:
          type: string
          description: 'How urgent: Blocker first.'
          enum:
          - Blocker
          - NotFound
          - NotChosen
          - Legibility
          - Emerging
        title:
          type: string
          description: What was found, in a sentence.
        locked:
          type: boolean
          description: True when measuring it needs an account (an AI engine asked, a Google account read).
        lockedReason:
          type:
          - string
          - 'null'
          description: What it needs, when locked.
      additionalProperties: false
externalDocs:
  description: Developers
  url: https://therankingfactory.com/developers