Bots API

A bot is the top-level object in MimicBot. Each bot owns its own crawl sources, indexed pages, extracted actions, widget configuration, and conversation history. You create one bot per site or product you want the assistant to answer questions about. The endpoints below manage the lifecycle of a bot — from initial creation through installation verification to deletion.

Every endpoint in this section is scoped to your agency via your Bearer token. See Authentication for how to obtain one.

Endpoints

• Create a bot
• List bots
• Get a bot
• Update a bot
• Delete a bot
• Verify install

The bot object

Field	Type	Description
id	string (uuid)	Internal bot id — use this in all /api/bots/{botId}/* paths.
publicId	string	The data-bot-id attribute the widget script uses on the client site. Shaped like bot_xxxxxxxxxx.
name	string	Human-readable bot name.
clientUrl	string | null	The root URL the bot was created for. Used as the default website source.
status	"draft" | "indexing" | "ready" | "error"	Current lifecycle state.
widgetConfig	object	Widget appearance and behavior (see below).
crawlConfig	object	Crawl schedule, max pages, robots.txt policy.
lastIndexedAt	string | null	ISO 8601 timestamp of the most recent successful index.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 of the last update.

widgetConfig

Field	Type	Default
assistantName	string	"Assistant"
primaryColor	string (hex #rrggbb)	"#2563EB"
logoUrl	string | null	null
welcomeMessage	string	"Hi! How can I help?"
position	"bottom-right" | "bottom-left"	"bottom-right"
poweredByEnabled	boolean	true
allowedOrigins	string[]	[]
suggestedQuestions	string[] (max 6)	[]
privacyPolicyUrl	string | null	null

crawlConfig

Field	Type	Default
schedule	"manual" | "daily" | "weekly"	"manual"
maxPages	number (1–5000)	500
respectRobotsTxt	boolean	true

Create a bot

POST /api/bots

Creates a bot, provisions a default website source rooted at clientUrl, and queues the first indexing crawl. Counts against the agency's plan bots limit.

Request body

Field	Type	Required	Description
name	string (1–200)	yes	Bot name.
clientUrl	string (URL)	yes	Root URL to index.
widgetConfig	object (partial)	no	Overrides for any field in widgetConfig.
crawlConfig	object (partial)	no	Overrides for any field in crawlConfig.

Request

curl https://api.mimicbot.app/api/bots \
  -H "Authorization: Bearer $MIMICBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Docs Bot",
    "clientUrl": "https://docs.acme.com"
  }'

Response 201

{
  "bot": {
    "id": "9c2e...",
    "publicId": "bot_a1B2c3D4e5",
    "name": "Acme Docs Bot",
    "clientUrl": "https://docs.acme.com",
    "status": "draft",
    "widgetConfig": { "assistantName": "Acme Docs Bot", "primaryColor": "#4F46E5" },
    "crawlConfig": { "schedule": "manual", "maxPages": 500, "respectRobotsTxt": true },
    "lastIndexedAt": null,
    "createdAt": "2026-04-13T10:00:00.000Z",
    "updatedAt": "2026-04-13T10:00:00.000Z"
  }
}

Errors: 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 402 PLAN_LIMIT_REACHED, 403 NO_AGENCY, 429 RATE_LIMITED (see Rate limits), 503 TEMPORAL_UNAVAILABLE. See Errors for the response shape.

List bots

GET /api/bots

Returns every non-deleted bot in the caller's agency, ordered by creation time.

Request

curl https://api.mimicbot.app/api/bots \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{ "bots": [ { "id": "...", "name": "Acme Docs Bot", "status": "ready" } ] }

Errors: 401 UNAUTHENTICATED, 403 NO_AGENCY, 429 RATE_LIMITED (see Rate limits). See Errors.

Get a bot

GET /api/bots/{botId}

Request

curl https://api.mimicbot.app/api/bots/$BOT_ID \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{ "bot": { "id": "...", "name": "Acme Docs Bot", "status": "ready" } }

Errors: 401 UNAUTHENTICATED, 403 NO_AGENCY, 404 NOT_FOUND, 429 RATE_LIMITED (see Rate limits). See Errors.

Update a bot

PATCH /api/bots/{botId}

Updates mutable bot fields. At least one of name or crawlConfig must be supplied. crawlConfig is shallow-merged with the existing value.

Request body

Field	Type	Description
name	string (1–200)	New bot name.
crawlConfig	object (partial)	Overrides for any subset of schedule, maxPages, respectRobotsTxt.

Request

curl -X PATCH https://api.mimicbot.app/api/bots/$BOT_ID \
  -H "Authorization: Bearer $MIMICBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "crawlConfig": { "schedule": "daily" } }'

Response 200

{ "bot": { "id": "...", "crawlConfig": { "schedule": "daily", "maxPages": 500 } } }

Errors: 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 403 NO_AGENCY, 404 NOT_FOUND, 429 RATE_LIMITED (see Rate limits). See Errors.

Delete a bot

DELETE /api/bots/{botId}

Soft-deletes the bot and cascades a soft delete to its pages. The bot is excluded from all list and get calls after this point. Sources, crawl jobs, and actions are cleaned up via cascade on the underlying rows.

Request

curl -X DELETE https://api.mimicbot.app/api/bots/$BOT_ID \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{ "ok": true }

Errors: 401 UNAUTHENTICATED, 403 NO_AGENCY, 404 NOT_FOUND, 429 RATE_LIMITED (see Rate limits). See Errors.

Verify install

POST /api/bots/{botId}/verify-install

Fetches the supplied url on the caller's behalf and searches the HTML for a <script data-bot-id="{publicId}"> tag matching this bot. Use this to give operators a "check my install" button in your onboarding flow. This endpoint never throws on fetch failure — a network or upstream error surfaces as { "installed": false, "error": "..." }.

Request body

Field	Type	Required
url	string (URL)	yes

Request

curl -X POST https://api.mimicbot.app/api/bots/$BOT_ID/verify-install \
  -H "Authorization: Bearer $MIMICBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://docs.acme.com" }'

Response 200

{
  "installed": true,
  "snippetFound": true,
  "httpStatus": 200
}

Errors: 400 VALIDATION_ERROR, 401 UNAUTHENTICATED, 403 NO_AGENCY, 404 NOT_FOUND, 429 RATE_LIMITED (see Rate limits). See Errors.