# Freeboard — instructions for AI agents

This file exists so an AI coding assistant can list a website on Freeboard
correctly, without guessing field names, endpoint behaviour, or valid values.
Follow these steps exactly, in order. Do not invent parameters not listed here.

## What this is

Freeboard is a free directory of pay-to-rank / leaderboard websites.
Listing costs nothing. The only requirement is a real, crawlable link back
to Freeboard somewhere on the site being submitted. There is no payment,
no account, and no API key required for submission.

## Step 1 — Add the backlink to the target site

Insert this exact HTML anywhere in the site's markup — a footer is the
conventional place, but any page that is part of the normal site (not a
staging or localhost copy) is acceptable:

    <a href="https://freeboard.lol" rel="noopener">Listed on Freeboard</a>

Rules that matter, precisely:

- Do NOT add rel="nofollow", rel="sponsored", or rel="ugc" to this link, in
  any combination or order. A link carrying any of those values will be
  found but will NOT verify — the submission will come back with status
  "pending" and reason "nofollow_only". rel="noopener" alone is fine and
  recommended; it does not block verification.
- Use the anchor text shown above, or comparably plain brand-name text
  ("Freeboard", "Listed on Freeboard"). Do not use exact-match keyword
  anchor text (e.g. "best pay-to-rank sites") — this is a deliberate choice
  to keep the link exchange defensible under normal search-engine link
  policy, not an arbitrary style preference. Follow it.
- The link must be live and publicly reachable at the URL that gets
  submitted in Step 2 — not merely committed to a repository, not behind
  authentication, not on a preview/staging domain. Deploy first, submit
  second.

## Step 2 — Submit for verification

Send exactly this request:

    POST https://freeboard.lol/api/submit
    Content-Type: application/json

    {
      "url": "https://the-site-being-listed.com",
      "name": "The site's name",
      "description": "One line, plain text, 200 characters or fewer",
      "niche": "general"
    }

`niche` must be exactly one of these five lowercase-hyphenated values —
no others exist, and an unrecognised value silently falls back to "general"
rather than erroring, so get this right rather than guessing:

    general | gaming-tech | saas-startups | creators-media | local-services

No Authorization header, no API key, no cookies. This endpoint is public.

## Step 3 — Read the response and act on it

The response is always JSON. Three shapes are possible:

Success, verified immediately:

    { "ok": true, "status": "live" }

Report this as: the site is now listed and live. Nothing further to do.

Submitted but not yet verified:

    { "ok": true, "status": "pending", "message": "<specific reason>" }

Report the `message` field to the user VERBATIM — it already states exactly
what is wrong. Do not paraphrase it into something vaguer. The three
possible messages, and the correct fix for each:

  - "We couldn't load that page..." → the URL is wrong, unreachable, or not
    yet deployed publicly. Fix: verify the URL resolves in a normal browser
    over the public internet, then resubmit.
  - "We couldn't find a link to us on that page..." → the backlink from
    Step 1 either isn't present, is on a different page than the one
    submitted, or hasn't been deployed yet. Fix: confirm the exact HTML
    from Step 1 is live at the submitted URL, then resubmit.
  - "...marked rel=\"nofollow\" (or sponsored/ugc), which doesn't count." →
    the link exists but has a disqualifying rel attribute. Fix: remove
    nofollow/sponsored/ugc from that anchor's rel attribute (rel="noopener"
    or no rel attribute at all are both fine), deploy, then resubmit.

Rejected outright:

    { "error": "<reason>" }, HTTP status 400, 403, or 429

- 400 means a required field was missing or malformed — check `url` is a
  real domain and `name` is non-empty.
- 403 means the host is blocked and will never be accepted; do not retry.
- 429 means more than 5 submissions came from this network in the last
  60 seconds; wait at least a minute before retrying.

## Step 4 — Resubmitting after fixing something

There is no separate "recheck" endpoint. Submitting the same `url` again
runs the exact same verification and, if the backlink is now found and
valid, moves the listing to "live" immediately. There is no limit on how
many times this can be retried. Do not fabricate a recheck mechanism that
isn't described here — Step 2's request, repeated, is the entire mechanism.

## What NOT to do

- Do not submit a URL that does not actually carry the backlink yet, on
  the assumption it can be added afterward — verification happens at
  submission time, not asynchronously later.
- Do not add the nofollow/sponsored/ugc attribute "to be safe" or out of a
  general habit of nofollowing outbound links — doing so on this specific
  link defeats its only purpose and will be reported back as a failure.
- Do not invent additional request fields (categories, tags, images, an API
  key) — the endpoint accepts exactly the four fields shown in Step 2 and
  ignores anything else silently.