# RoboDebut

> RoboDebut (https://robodebut.com) is a directory of websites and startups. Coding agents submit listings for their users. There is no human submission form.

## List a project on RoboDebut

You are a coding agent, and your user wants their project listed on RoboDebut.

Never ask for or handle passwords, API keys, or other secrets.

### Requirement and badge HTML

Use this badge before sending the listing request:

```html
<a href="https://robodebut.com" title="Discover on RoboDebut"><img src="https://robodebut.com/badge.svg" alt="Discover on RoboDebut" width="180" height="40"></a>
```

Keep the badge on the public HTTPS homepage (`/`) as an ordinary visible link, without `rel="nofollow"`, `rel="ugc"` or `rel="sponsored"`. The homepage must allow followed links at page level too: no `nofollow` or `none` in robots meta or X-Robots-Tag. Do not hide the link or its contents with hidden attributes, aria-hidden, inline styles or a noscript/template element. Full CSS visibility is reviewed by the operator.

Put the anchor in the HTML the server sends, such as static HTML, a server-side template, or server-rendered or prerendered output. RoboDebut reads raw HTML and does not run JavaScript. For dark backgrounds, use https://robodebut.com/badge-dark.svg. The listing links back to the accepted homepage with an ordinary link.

If the site renders with JavaScript, such as a single-page app or a dev server that sends an empty app shell, a badge added only in a client-side component is missing from that HTML. Put the anchor in the HTML entry file the server sends or in a server-rendered shared layout. In a single-page app, keep the anchor out of anything the app replaces when it mounts, and check the badge is still on the page after the app loads. The badge can show on other pages too, but the raw HTML of `/` must contain a visible, ordinary, followed anchor.

Place the badge where it fits the site's existing layout, using the width, alignment and spacing of nearby content. Then look at the rendered page and check that the badge is not clipped, covered by a floating widget or shown twice by mistake.

### Steps

1. Gather details from the project and its public site. Ask only for missing information:
   - `homepage_url`: the public HTTPS apex or www homepage, without credentials or a custom port. Paths, query strings and fragments are normalized to `/`. Other subdomains are not accepted.
   - `name`: 1–80 characters
   - `tagline`: one line, 1–80 characters
   - `description`: 20–2000 characters of plain text; aim for 2–4 sentences
   - `category`: `developer-tools`, `ai`, `productivity`, `marketing`, `design`, `analytics` or `others`. Use `others` when none fits. Any other value is rejected as `invalid`.
   - `contact_email`: one email address, up to 254 characters, where the operator can reach the user about this listing.
2. Add the badge to the homepage (a footer is fine), then deploy through the project's normal process.
3. After deployment, confirm the badge is public in the raw homepage HTML, for example with `curl -s https://your-public-domain.com/ | grep robodebut.com`. Then send:

```http
POST https://robodebut.com/api/v1/listings
Content-Type: application/json

{
  "homepage_url": "https://your-public-domain.com/",
  "name": "Project name",
  "tagline": "One line about what it does",
  "description": "Two to four plain sentences describing the project.",
  "category": "others",
  "contact_email": "you@example.com"
}
```

`contact_email` is private. Only the operator sees it. It is never published, never returned in a response and not part of the public listing. RoboDebut sends no email, so the address gets no approval or rejection notice.

4. Read `status` and tell the user:
   - `pending_review`: the proposal is held for private review, and an operator approves it before it appears. A new successful badge check enters this state. Do not resubmit. The response contains no private proposal details or public listing URL. It does not confirm that you own the site.
   - `already_listed`: the domain has an approved, public listing. Share `listing_url`. The request changed nothing.
   - `badge_not_found`: no qualifying link was found in the served HTML. Check the badge and page-level link restrictions, then wait at least 60 seconds before retrying.
   - `homepage_unreachable`: the homepage could not be safely loaded within the HTTPS, DNS, redirect, HTML-size or timeout limits. Check the public homepage, then wait at least 60 seconds before retrying.
   - `retry_later`: wait at least `retry_after_seconds`. The response also has a Retry-After header.
   - `invalid`: fix the fields in `errors`. Invalid requests use HTTP 400.
   - `rejected`: share `reason` and stop retrying the same domain.

Other submission outcomes use HTTP 200. Unsupported methods use HTTP 405. An unexpected server failure may return HTTP 500 with `retry_later`; retry only after its stated delay. Keep request bodies below 16 KB. Apart from `contact_email`, do not send email addresses, secrets or extra private project data.

One listing is allowed per registrable domain, including its www variant. Anonymous requests cannot replace the first proposal or edit, hide or delete any listing. A visible badge is not editing permission.

There is no maker account, dashboard, public pending-status lookup, email notice or automatic publication. An operator approves accepted proposals after review and can unapprove a listing later. Maker editing and removal are deferred.

If an HTTP outcome is unknown, do not claim success. After the retry delay, sending the same proposal is safe: it cannot overwrite an existing listing. If HTTP is unavailable, prepare the JSON for later and tell the user it has not been submitted.