Public API

A directory bots can read

List the catalog, submit a template, or add an 𝕏 post to the showcase. No API key. The API returns JSON and supports cross-origin requests.

List bots

The published directory as JSON, newest first. CORS is open. No API key.

GEThttps://grokbots.best/api/bots

Request

GET https://grokbots.best/api/bots

Response

Field	Meaning
`id`	Directory id.
`slug`	URL slug.
`name`	Display name from x.ai.
`description`	Short summary from x.ai.
`author`	𝕏 handle, or null.
`url`	Directory page, such as `https://grokbots.best/bots/…`
`source_url`	𝕏 status URL, or null.
`integrations`	Integration slugs used by the bot.
`created_at`	When it was added.

[
  {
    "id": "…",
    "slug": "example-bot",
    "name": "Example Bot",
    "description": "…",
    "author": "@handle",
    "url": "https://grokbots.best/bots/example-bot",
    "source_url": "https://x.com/handle/status/123",
    "integrations": ["github"],
    "created_at": "2026-04-01T00:00:00.000Z"
  }
]

Status 200 is an array of published bots. 500 if the directory fails to load.

Submit a bot

POST a public Grok Bot template link. We fetch the name and description from x.ai, then publish it to the directory. Do not send name or description yourself. x.ai often omits connectors, so you can pass integrations yourself.

POSThttps://grokbots.best/api/bots/submit

Request

Field	Meaning	Required
`link`	A template URL like `https://x.ai/bot/…`	yes
`source_url`	An 𝕏 status URL.	no
`author`	An 𝕏 handle such as @handle.	no
`integrations`	Names or slugs such as `github`. If omitted, we use what we can detect from x.ai.	no

POST https://grokbots.best/api/bots/submit
Content-Type: application/json

{
  "link": "https://x.ai/bot/ph5mcXqVy2p176Br7BJYi",
  "source_url": "https://x.com/handle/status/123",
  "author": "@handle",
  "integrations": ["github", "pstack"]
}

Response

Field	Meaning
`slug`	URL slug of the published bot.
`url`	Directory path, such as `/bots/…`.

{
  "slug": "example-bot",
  "url": "/bots/example-bot"
}

Status 200 with slug and url. 409 if already in the directory. 404 if the template is not on x.ai. 400 for an invalid link, post URL, handle, or integrations. 503 if saving is not configured.

Add a showcase post

POST a public 𝕏 status URL. We add it to the showcase feed. No API key.

POSThttps://grokbots.best/api/feed

Request

Field	Meaning	Required
`url`	An 𝕏 status URL, like `https://x.com/user/status/…`	yes

POST https://grokbots.best/api/feed
Content-Type: application/json

{
  "url": "https://x.com/handle/status/123"
}

Response

Field	Meaning
`id`	Saved post id.
`url`	Canonical 𝕏 status URL.

{
  "id": "…",
  "url": "https://x.com/handle/status/123"
}

Status 200 with id and url. 409 if already in the feed. 400 for an invalid 𝕏 post URL. 503 if saving is not configured.

Send this page to a bot

This page documents the public endpoints. Give a bot https://grokbots.best/api and ask it to list the directory, submit a template, or add a showcase post.