TemplateBot/HTTP API

HTTP API

Agents and humans: call these routes. Do not scrape templatebot.lol HTML, cards, or llms.txt as a substitute for publish.

Use the API or MCP

Browse listings on the website. To preview or publish a Grok Bot template, use this HTTP API or attach MCP at https://templatebot.lol/mcp. Scraping share pages, the board, or search HTML is unsupported and will miss Sale gating, auth, and fail-loud errors.

Base URL

Production origin is https://templatebot.lol. All routes below are on that host.

Auth

Anonymous publish is rejected. Send one of:

  • Authorization: Bearer <owner token> — signed-in users copy tbown_… from the Dashboard. Publishes as that account.
  • Authorization: Bearer <AGENT_API_KEY> — operator key (wrangler secret). Publishes unowned listings. Cannot take over a Clerk-owned listing (403).
  • A signed-in Clerk session cookie on templatebot.lol (same as the website).

Missing or invalid credentials fail loud: HTTP 401 JSON { "error": "unauthorized", "hint": "…" } with WWW-Authenticate. If no operator key is configured and Clerk is off, POST may return 503 AGENT_API_KEY is not configured.

POST /api/agent/templates

Create a listing or resubmit a new version of the same share id. Same rules as the website submit form. Owner token, operator key, or Clerk session.

Body JSON: shareUrl (required — https://x.ai/bot/{id}, a bare share id, or an X post URL that contains an x.ai/bot link). Optional: category, description, instructions, setupNotes, integrations, resubmit.

resubmit: true requires an existing listing and saves a new version. resubmit: false fails if already listed. Omit to create, or version when allowed. You cannot version someone else’s listing (403).

Query ?preview=1 fetches and validates without writing (same as MCP preview_template).

Success: 200 with ok: true and url like https://templatebot.lol/bot/{shareId}.

POST https://templatebot.lol/api/agent/templates
Authorization: Bearer <owner token>
Content-Type: application/json

{ "shareUrl": "https://x.ai/bot/lkkCqhC1jBFp6ouZOQd9m", "resubmit": true, "category": "Sales" }

GET /api/agent/templates

Operator backfill only — AGENT_API_KEY. Lists published templates for category / integration analysis.

  • ?limit=50 (max 100)
  • ?needsCategory=1 (default) — Other/empty categories only
  • ?needsCategory=0 — all published, still capped

PATCH /api/agent/templates

Operator backfill only — AGENT_API_KEY. Body { "updates": [{ "id" | "shareUrl", "category?", "integrations?", "description?" }, ...] }. Max 100 updates. Each row fails independently with a per-id error string (invalid category, not found, …).

GET /api/featured

Public. Top 5 or Top 10 published Grok Bot templates by marketplace score (same formula as auto-feature). Query ?limit=5 or ?limit=10 (default 10). No auth. Sale listings omit install URLs. Live upvote/open counts are real marketplace stats — do not invent extras. Hunt CLI: node scripts/hunt.mjs featured.

GET /api/changelog

Public index of published changelog entries (slug, title, permalink, featured ids). HTML: /changelog.

POST /api/agent/changelog

Operator only — AGENT_API_KEY. Publish a short public changelog entry. You write the copy; TemplateBot stores and renders it. Owner tokens are rejected (403).

Body JSON: title (required), body (required), optional featuredIds (share ids or x.ai URLs, max 10), optional slug. Success includes url /changelog/{slug}.

POST /api/agent/changelog
Authorization: Bearer <AGENT_API_KEY>
Content-Type: application/json

{ "title": "This week’s featured bots", "body": "…", "featuredIds": ["lkkCqhC1jBFp6ouZOQd9m"] }

Fail loud

Do not retry blindly. Typical JSON errors:

  • 400 — invalid JSON, missing shareUrl, bad category/integrations
  • 401 — missing/invalid bearer (or not signed in)
  • 403 — another account owns the listing
  • 404 — resubmit: true but not listed yet
  • 409 — already listed and resubmit: false
  • 503 — database unavailable, or operator key missing

Free vs Sale

POST publish is Free-only. priceCents is ignored. Set a Sale price on the website. Existing Sale listings keep their price on resubmit. Unpaid Sale install URLs are omitted from public HTML/JSON — do not scrape around that.

APIMCPChangelogDashboardAbout