API: Manifests

Endpoints for reading and updating a bot's manifest. The manifest defines a bot's runtime capabilities, webhook delivery configuration, and action parameters.

Get Manifest

GET /api/v1/bots/:botId/manifest

Returns the bot's current manifest.

---

Update Manifest

PUT /api/v1/bots/:botId/manifest

Updates the bot's manifest. Requires Write or Admin permission. You can include any combination of the sections below; unspecified sections remain unchanged.

Example:

curl -X PUT \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": {
      "proxy": true,
      "locale": "en-US",
      "timezone": "America/New_York"
    },
    "webhook": {
      "url": "https://api.example.com/ingest",
      "auth": "hmac",
      "secret": "whsec_..."
    }
  }' \
  "https://<deployment>.convex.site/api/v1/bots/<botId>/manifest"

---

Manifest Structure

capabilities

Browser configuration applied when the bot executes.

Field	Type	Description
proxy	boolean	Enable proxy routing for this bot.
locale	string	Browser locale (e.g., en-US, fr-FR).
userAgent	string	Custom User-Agent string.
timezone	string	Browser timezone (e.g., America/New_York).
geolocation	object	GPS coordinates (latitude, longitude) for geolocation spoofing.
adBlocking	boolean	Enable ad and tracker blocking.
resolution	object	Browser viewport dimensions (width, height).
timeout	number	Maximum execution time in seconds.

webhook

Configuration for delivering extracted data to external endpoints after successful execution. See Webhooks for full details on authentication methods.

Field	Type	Description
url	string	Destination URL for webhook delivery.
auth	string	Authentication method: none, hmac, or jwt.
secret	string	HMAC secret key (when auth is hmac).
loginUrl	string	Login endpoint URL (when auth is jwt).
username	string	Login username (when auth is jwt).
password	string	Login password (when auth is jwt).
dataPath	string	Dot-notation path to extract a specific field from the output (e.g., results.items).

parameters

For action bots, defines the expected input parameters that callers must provide when triggering an execution.

Field	Type	Description
name	string	Parameter name.
type	string	Expected type (e.g., string, number, boolean).
description	string	Human-readable description of what the parameter controls.
required	boolean	Whether the parameter must be provided.

Example parameters definition:

{
  "parameters": [
    {
      "name": "searchQuery",
      "type": "string",
      "description": "The search term to look up",
      "required": true
    },
    {
      "name": "maxResults",
      "type": "number",
      "description": "Maximum number of results to return",
      "required": false
    }
  ]
}

When an execution is triggered via the API, the provided parameters are validated against this definition. See Executions for details on passing parameters.