Actions API

An action is a capability the bot can execute on behalf of a visitor — subscribing them to a newsletter, opening a contact form, starting a mailto draft, booking a calendar slot, calling a phone number, or launching WhatsApp. Actions are discovered during the crawl by a capability extractor, which proposes them in review status for an operator to approve. Once active, the bot can propose them to visitors and record executions. These endpoints are how dashboards (and your own tooling) manage the action queue and inspect the execution history.

Endpoints

• List actions
• Update action status
• List executions

The action object

Field	Type	Description
id	string (uuid)	Action id.
botId	string (uuid)	Owning bot.
sourcePageId	string | null	Page the capability was extracted from.
kind	"newsletter" | "contact_form" | "mailto" | "calendar" | "phone" | "whatsapp"	Capability category.
status	"active" | "review" | "disabled" | "dropped"	Lifecycle. Only active actions are proposed in chat.
executionMode	"widget" | "server"	Who runs the action — the embedded widget or the server.
label	string	Short human-readable label.
description	string	Longer human-readable description.
paramsSchema	object	JSON-schema–shaped description of the params the widget collects.
target	object	Kind-specific target metadata (for example, a URL, phone number, or form selector).
confidence	number (0–1)	Extractor confidence score.
lastSeenInCrawlAt	string	ISO 8601 of the crawl in which this action was last observed.
enabledAt	string | null	When it was first activated.
disabledAt	string | null	When it was last disabled.
createdAt	string	ISO 8601.
updatedAt	string	ISO 8601.

List actions

GET /api/bots/{botId}/actions

Returns every action for a bot, ordered by confidence descending.

Query parameters

Name	Type	Description
status	"active" | "review" | "disabled" | "dropped"	Optional filter by lifecycle status.

Request

curl "https://api.mimicbot.app/api/bots/$BOT_ID/actions?status=review" \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{
  "items": [
    {
      "id": "...",
      "botId": "...",
      "kind": "newsletter",
      "status": "review",
      "executionMode": "widget",
      "label": "Subscribe to the newsletter",
      "description": "Weekly product updates.",
      "confidence": 0.92,
      "paramsSchema": { "email": { "type": "string" } },
      "target": { "formSelector": "#newsletter" }
    }
  ]
}

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

Update action status

PATCH /api/bots/{botId}/actions/{actionId}

Transitions an action between review, active, disabled, and dropped. Moving to active stamps enabledAt; moving to disabled stamps disabledAt.

Request body

Field	Type	Required
status	"active" | "review" | "disabled" | "dropped"	yes

Request

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

Response 200

{ "item": { "id": "...", "status": "active", "enabledAt": "2026-04-13T10:00:00.000Z" } }

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

List executions

GET /api/bots/{botId}/actions/executions

Returns the most recent action executions across every action on the bot, ordered by createdAt descending.

Query parameters

Name	Type	Default	Description
limit	number (1–100)	20	Maximum rows to return.

Request

curl "https://api.mimicbot.app/api/bots/$BOT_ID/actions/executions?limit=50" \
  -H "Authorization: Bearer $MIMICBOT_TOKEN"

Response 200

{
  "items": [
    {
      "id": "...",
      "actionId": "...",
      "actionLabel": "Subscribe to the newsletter",
      "actionKind": "newsletter",
      "visitorId": "visitor_abc",
      "result": "success",
      "error": null,
      "createdAt": "2026-04-13T10:00:00.000Z",
      "completedAt": "2026-04-13T10:00:01.500Z"
    }
  ]
}

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