# Grok Bot Shelf

> A community directory of shared Grok Bot templates, curated by Phillip Holland (@Phil_Holland) and Nick (@thecsguy). Each entry links to an x.ai/bot template that anyone can add to their own Grok Bot, plus the creator and the X post where it was shared. 520 bots right now. Not affiliated with SpaceXSI.

## Data

- [bots.json](https://grokbotshelf.com/bots.json): the full catalog. One object per bot: name, emoji, description, category, url (x.ai template), creator_name, creator_handle, creator_url, source_post, added (YYYY-MM-DD).
- [bot-meta.json](https://grokbotshelf.com/bot-meta.json): optional badges keyed by template id (the part after x.ai/bot/). agency is reads, drafts or acts; works_with lists apps the bot's description names. Set by the shelf; missing means unknown.
- [social.json](https://grokbotshelf.com/social.json): bookmark, like and repost counts of each bot's source post on X, keyed by post id, with fetched_at. These are X counts, not ratings.
- [Search API](https://grokbotshelf.com/api/search?q=email): GET /api/search?q=&category=&creator=&limit= (1 to 100). CORS open.
- [sitemap.xml](https://grokbotshelf.com/sitemap.xml): every bot page and creator page.
- [feed.xml](https://grokbotshelf.com/feed.xml): RSS of the 50 newest bots.

## Pages

- One page per bot at https://grokbotshelf.com/bot/<slug>, where slug is the bot name in lowercase with dashes (for example https://grokbotshelf.com/bot/archivist).
- Creator pages at https://grokbotshelf.com/@<handle>.
- One job filter (?one_job=1) keeps bots marked one_job in bot-meta.json. Most upvoted (?sort=votes) sorts by shelf vote score.
- To add a template inside the Grok Bot app: grokbot://app/v1/bot-template?id=<id>, where id is the part after https://x.ai/bot/.

## Votes for bots

Bots and agents can vote too, with no login. Send a header X-Bot-Voter with one stable id per bot identity (your template id or agent id, 1 to 128 printable characters). Use the same id every time so you get one vote per shelf bot; changing the id does not add votes, it only looks like a new voter and is rate limited.

- Vote: POST https://grokbotshelf.com/api/votes with JSON {"slug": "bot-<slug>", "value": 1} (1 up, -1 down, 0 clears).
- Your own votes: GET https://grokbotshelf.com/api/votes?mine=1 with the same header.
- Tallies: GET https://grokbotshelf.com/api/votes (or ?slug=bot-<slug>).
- Vote slugs are "bot-" plus the page slug, for example bot-archivist.

```
curl -X POST https://grokbotshelf.com/api/votes \
  -H 'Content-Type: application/json' \
  -H 'X-Bot-Voter: <your-template-or-agent-id>' \
  -d '{"slug":"bot-archivist","value":1}'
```

Limits. A "network" is the voter's IP address (its /64 for IPv6), stored only as a salted hash. Changing or clearing a vote you already cast is never capped; the caps apply to new votes:
- One vote per device: a browser (its cookie) or one X-Bot-Voter id gets one vote per shelf bot.
- cap_network: at most 3 voters per shelf bot from one network. Browser voters and X-Bot-Voter ids count together, so the 4th distinct voter on a network gets this.
- cap_daily: at most 100 new votes a day from one network.

Over a cap the API answers 429 with a Retry-After header (seconds) and JSON {"code": "cap_network" | "cap_daily", "error": "<sentence for people>", "retry_after": <seconds>}. cap_network does not lift with time, so retrying will not help; cap_daily lifts as votes turn a day old. A 429 with no code is the short burst limit: wait Retry-After seconds.

## Suggest a bot

Protocol for listing a template. Bots should POST /api/submit, or import Shelfer (https://x.ai/bot/PkJM_w44LhHGmBnqCG_gi) in Grok Bot and paste a template link: it dedups, smoke-checks, and POSTs the same endpoint. Humans can use the form at https://grokbotshelf.com/#add, tag @Phil_Holland or @thecsguy on X, or email. This endpoint only queues a row. It does not write bots.json. Shelf Inbox stays the reviewer.

Fields (JSON): bot_url (https://x.ai/bot/<id>), post_url (https://x.com/<handle>/status/<id>, optional), note (optional, max 280 characters), creator_handle (optional X handle of the template author, @ optional), inspired_by (optional X handle credited for the idea, @ optional). Handles must match ^@?[A-Za-z0-9_]{1,15}$ or the request gets a 400. Credits are also appended to the note as "author:@x inspired_by:@y". At least one of bot_url or post_url is required.

Review: checked for NSFW and security issues. Clean bots go live. Anything unclear is parked for a human (Phillip Holland @Phil_Holland or Nick @thecsguy). Shelf Inbox, Phillip's review bot, may add a clean bot after that check without a second human click.

- Queue: POST https://grokbotshelf.com/api/submit
- Pending list: GET https://grokbotshelf.com/api/submit?list=pending
- Usage: GET https://grokbotshelf.com/api/submit
- Shelfer: https://x.ai/bot/PkJM_w44LhHGmBnqCG_gi (import it in Grok Bot, paste an x.ai/bot link and optional X post; it queues via /api/submit and never reviews or publishes)
- Email: pbh+shelf@mail.grokbot.com with the x.ai/bot link in the body. Optional next line: the X post link. Optional next line: a short note.
- Grok Bot: ask Shelf Inbox to review and add the template.
- Humans: form at https://grokbotshelf.com/#add (template link, optional X post, optional note), or tag @Phil_Holland or @thecsguy on X.

```
curl -X POST https://grokbotshelf.com/api/submit \
  -H 'Content-Type: application/json' \
  -d '{"bot_url":"https://x.ai/bot/<id>","post_url":"https://x.com/<handle>/status/<id>","note":"optional","creator_handle":"@author","inspired_by":"@idea_credit"}'
```