API: Bots
Endpoints for listing, creating, and inspecting bots.
List Bots
GET /api/v1/bots
Returns all bots in the organization. Supports cursor-based pagination.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number | Maximum number of bots to return. |
cursor | string | Pagination cursor from a previous response. |
Response Fields:
| Field | Type | Description |
|---|---|---|
id | string | Unique bot identifier. |
name | string | Bot name. |
targetUrl | string | URL the bot targets. |
kind | string | extraction or action. |
status | string | Current bot status. |
tags | string[] | Tags assigned to the bot. |
createdAt | number | Creation timestamp (Unix ms). |
Example:
curl -H "Authorization: Bearer <api-key>" \
"https://<deployment>.convex.site/api/v1/bots?limit=10"
Create Bot
POST /api/v1/bots
Creates a new bot. Requires Write or Admin permission.
Request Body:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Bot name. |
targetUrl | string | Yes | URL the bot will target. |
description | string | No | Description of what the bot does. |
kind | string | No | extraction (default) or action. |
tags | string[] | No | Tags for organizing bots. |
Example:
curl -X POST \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-d '{"name": "Price Monitor", "targetUrl": "https://example.com/products", "kind": "extraction"}' \
"https://<deployment>.convex.site/api/v1/bots"
Get Bot Details
GET /api/v1/bots/:botId
Returns full details for a specific bot.
Get Bot Steps
GET /api/v1/bots/:botId/steps
Returns the recorded steps for a bot. These are the interactions captured during recording sessions.
Get Bot Scripts
GET /api/v1/bots/:botId/scripts
Returns the scripts associated with a bot (generated or manually written automation code).
Get Latest Extraction
GET /api/v1/bots/:botId/latest-extract
Returns the extracted data from the bot's most recent successful execution. Useful for polling the current state of an extraction bot without listing all executions.
Get Latest Execution
GET /api/v1/bots/:botId/latest-execution
Returns the most recent execution for the bot, regardless of its outcome.
Get Schedule
GET /api/v1/bots/:botId/schedule
Returns the bot's schedule configuration, including interval and whether the schedule is active.