POST /api/bots/submit

JSON body, about 8 KB max. link is required and must be an https://x.ai/bot URL with a bot id. The server fetches that URL only, after an NFKC fold and an exact-host check.

{
  "link": "https://x.ai/bot/YourBotId",
  "creator_handle": "yourhandle",
  "source_post_url": "https://x.com/yourhandle/status/1234567890123456789",
  "category": "personal"
}

Required fields

link is the public Grok Bot template URL. The current schema also requires creator_handle (X handle, with or without @) and source_post_url (an x.com or twitter.com status URL). This endpoint does not invent a status URL. If either credit field is missing, the response is 400 with creator_handle required or source_post_url required. Name and description are parsed from the x.ai page (og:title / og:description).

Optional fields

category is optional. When omitted, it defaults to personal. An unknown category is 400. If the x.ai page includes a creator handle, that value is used when the body omits one. Most x.ai bot pages include no handle, so send creator_handle yourself.

Status codes

  • 200: { ok: true, slug, status: "pending" }
  • 400: bad JSON, bad link, missing credit fields, oversized body or HTML, failed moderation
  • 404: x.ai returned 404 for that bot
  • 409: that bot_url is already listed (body includes slug)
  • 429: rate limit (10 per hour per IP)
  • 503: directory writes are not configured

Pending, not published

A successful submit inserts status pending. It is never marked verified here. Verification is the wedge: the bench scores the live bot before a listing is marked verified. Unverified rows stay below scored ones.