API Documentation

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header. Generate keys from your dashboard under Settings → API Keys.

curl https://api.hidettp.dev/api/v1/bots \
  -H "Authorization: Bearer bm_your_api_key"

API keys use the bm_ prefix. Each key is scoped to an organization and assigned a permission level:

Permission	Access
`read`	Read-only access to bots, executions, scripts, manifests, and schedules
`write`	Everything in `read` plus create/update bots, trigger executions, manage scripts and schedules
`admin`	Everything in `write` plus delete bots and manage API keys

API keys are hashed server-side with SHA-256. The raw key is shown only once at creation—store it securely.

Base URL

All endpoints are served under:

https://api.hidettp.dev/api/v1

All requests and responses use Content-Type: application/json. CORS is enabled for all origins.

Response Format

Successful responses wrap data in a data envelope. Paginated responses include a meta object:

// Single resource
{
  "data": {
    "id": "k57abc123def456",
    "name": "Price Monitor",
    "status": "active"
  }
}

// Paginated list
{
  "data": [/* items */],
  "meta": {
    "limit": 20,
    "hasMore": true,
    "nextCursor": "eyJ2IjoiMTcx..."
  }
}

Created resources return 201 with a Location header pointing to the new resource.

Pagination

List endpoints use cursor-based pagination. Pass limit and cursor as query parameters:

Parameter	Type	Default	Description
limit	integer	20	Number of items to return (1–100)
cursor	string	—	Opaque cursor from a previous response's `meta.nextCursor`

# First page
GET /api/v1/bots?limit=10

# Next page
GET /api/v1/bots?limit=10&cursor=eyJ2IjoiMTcx...

Error Handling

Errors return a JSON body with a structured error object:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Bot not found",
    "details": {
      "id": "k57abc123def456"
    }
  }
}

HTTP Status	Error Code	Description
`400`	`BAD_REQUEST`	Invalid request body or parameters
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Insufficient permission level
`404`	`NOT_FOUND`	Resource does not exist or not accessible
`405`	`METHOD_NOT_ALLOWED`	HTTP method not supported on this resource
`409`	`CONFLICT`	Resource state conflict
`422`	`VALIDATION_ERROR`	Request body fails validation
`500`	`INTERNAL_ERROR`	Unexpected server error

List Bots

Returns a paginated list of bots in your organization.

GET /api/v1/bots

Query parameters

Parameter	Type	Description
status	string	Filter by status: `active`, `inactive`, `error`, `paused`, `archived`, `failed`
tag	string	Filter by tag
limit	integer	Max results per page (default 20, max 100)
cursor	string	Pagination cursor

Response

{
  "data": [
    {
      "id": "k57abc123def456",
      "name": "Price Monitor",
      "url": "https://store.example.com",
      "description": "Monitors competitor prices daily",
      "tags": ["pricing", "ecommerce"],
      "status": "active",
      "lastRunAt": "2025-03-14T10:30:00.000Z",
      "createdAt": "2025-01-10T08:00:00.000Z"
    }
  ],
  "meta": {
    "limit": 20,
    "hasMore": false
  }
}

Get Bot

Returns a single bot by ID.

GET /api/v1/bots/{botId}

Response

{
  "data": {
    "id": "k57abc123def456",
    "name": "Price Monitor",
    "url": "https://store.example.com",
    "description": "Monitors competitor prices daily",
    "tags": ["pricing"],
    "status": "active",
    "lastRunAt": "2025-03-14T10:30:00.000Z",
    "createdAt": "2025-01-10T08:00:00.000Z"
  }
}

Create Bot

Creates a new bot. Requires write permission.

POST /api/v1/bots

Request body

Field	Type	Required	Description
name	string	Yes	Display name for the bot
url	string	Yes	Target URL for the bot
description	string		Optional description
tags	string[]		List of tags for filtering

curl -X POST https://api.hidettp.dev/api/v1/bots \
  -H "Authorization: Bearer bm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price Monitor",
    "url": "https://store.example.com",
    "description": "Monitors competitor prices daily",
    "tags": ["pricing", "ecommerce"]
  }'

Response 201 Created

{
  "data": {
    "id": "k57abc123def456",
    "name": "Price Monitor",
    "url": "https://store.example.com",
    "description": "Monitors competitor prices daily",
    "tags": ["pricing", "ecommerce"],
    "status": "active",
    "createdAt": "2025-03-14T10:30:00.000Z"
  }
}

Update Bot

Partially updates a bot. Requires write permission. Only provided fields are changed.

PATCH /api/v1/bots/{botId}

Request body

Field	Type	Description
name	string	Updated name
url	string	Updated target URL
description	string	Updated description
tags	string[]	Updated tags (replaces existing)
status	string	One of: `active`, `inactive`, `paused`, `archived`

Response — returns the updated bot object (same shape as Get Bot).

Delete Bot

Permanently deletes a bot and all associated data. Requires admin permission.

DELETE /api/v1/bots/{botId}

Response 204 No Content

This action is irreversible. All executions, scripts, schedules, and manifests associated with the bot will be permanently removed.

Bot Steps

Returns the parsed steps from the bot's active script.

GET /api/v1/bots/{botId}/steps

Response

{
  "data": {
    "botId": "k57abc123def456",
    "steps": [
      { "name": "Navigate to site", "type": "navigate" },
      { "name": "Click login", "type": "click" },
      { "name": "Extract prices", "type": "action" }
    ],
    "scriptVersion": 3
  }
}

Latest Extract

Returns the most recent extracted data from the bot's last successful execution.

GET /api/v1/bots/{botId}/latest-extract

Response

{
  "data": {
    "executionId": "j57exec789abc",
    "extractedAt": "2025-03-14T10:35:00.000Z",
    "values": {
      "price": 29.99,
      "availability": "In Stock"
    }
  }
}

Returns null in data if the bot has no completed executions with extracted values.

Latest Execution

Returns the most recent execution for a bot, regardless of status.

GET /api/v1/bots/{botId}/latest-execution

Response

{
  "data": {
    "id": "j57exec789abc",
    "status": "success",
    "startedAt": "2025-03-14T10:30:00.000Z",
    "completedAt": "2025-03-14T10:35:00.000Z",
    "errorMessage": null
  }
}

Create Execution

Triggers a new execution for a bot. Requires write permission. The execution is queued and processed asynchronously.

POST /api/v1/bots/{botId}/executions

Request body (optional)

Field	Type	Required	Description
parameters	object		Runtime parameters for the bot (action bots may require specific parameters defined in their manifest)

curl -X POST https://api.hidettp.dev/api/v1/bots/{botId}/executions \
  -H "Authorization: Bearer bm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "ticketCount": 2,
      "eventDate": "2025-03-15",
      "section": "VIP"
    }
  }'

Response 201 Created

{
  "data": {
    "id": "j57exec789abc",
    "status": "pending",
    "startedAt": "2025-03-14T10:30:00.000Z",
    "parameters": {
      "ticketCount": 2,
      "eventDate": "2025-03-15",
      "section": "VIP"
    }
  }
}

Parameter validation depends on the bot's manifest. If the manifest defines required parameters, they must be provided or the request will return 400. Date parameters must use YYYY-MM-DD format.

List Executions

Returns a paginated list of executions for a bot.

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

Query parameters

Parameter	Type	Description
status	string	Filter: `pending`, `processing`, `success`, `failed`, `cancelled`, `timeout`
limit	integer	Max results per page (default 20, max 100)
cursor	string	Pagination cursor

Response

{
  "data": [
    {
      "id": "j57exec789abc",
      "status": "success",
      "startedAt": "2025-03-14T10:30:00.000Z",
      "completedAt": "2025-03-14T10:35:00.000Z",
      "errorMessage": null,
      "hasSteps": true,
      "hasFailed": false
    }
  ],
  "meta": {
    "limit": 20,
    "hasMore": false
  }
}

Get Execution

Returns a single execution by ID.

GET /api/v1/executions/{executionId}

Response

{
  "data": {
    "id": "j57exec789abc",
    "botId": "k57abc123def456",
    "status": "success",
    "startedAt": "2025-03-14T10:30:00.000Z",
    "completedAt": "2025-03-14T10:35:00.000Z",
    "errorMessage": null,
    "hasSteps": true,
    "hasFailed": false,
    "outputType": "extract"
  }
}

Cancel Execution

Cancels a running or pending execution. Requires write permission.

POST /api/v1/executions/{executionId}/cancel

Response

{
  "data": {
    "cancelled": true
  }
}

Returns 400 if the execution has already completed or cannot be found.

Execution Steps

Returns all steps from an execution with timing, status, and output data.

GET /api/v1/executions/{executionId}/steps

Response

{
  "data": {
    "executionId": "j57exec789abc",
    "status": "success",
    "startedAt": "2025-03-14T10:30:00.000Z",
    "completedAt": "2025-03-14T10:35:00.000Z",
    "steps": [
      {
        "index": 0,
        "name": "Navigate to site",
        "status": "completed",
        "durationMs": 1200,
        "output": null,
        "error": null,
        "screenshotUrl": null
      }
    ],
    "consolidatedExtract": {
      "price": 29.99
    }
  },
  "meta": {
    "totalSteps": 5,
    "completedSteps": 5,
    "totalDurationMs": 4800
  }
}

Single Step

Returns a single step from an execution by its zero-based index.

GET /api/v1/executions/{executionId}/steps/{stepIndex}

Response

{
  "data": {
    "index": 2,
    "name": "Extract prices",
    "status": "completed",
    "durationMs": 850,
    "output": { "price": 29.99 },
    "error": null
  }
}

Step Screenshot

Returns the failure screenshot for a step as a PNG image. Only available for the step where the execution failed.

GET /api/v1/executions/{executionId}/steps/{stepIndex}/screenshot

Response — 200 with Content-Type: image/png binary data, or 404 if no screenshot is available for that step.

Execution Extract

Returns the consolidated extracted data from all steps of an execution, merged with any top-level output.

GET /api/v1/executions/{executionId}/extract

Response

{
  "data": {
    "executionId": "j57exec789abc",
    "extractedAt": "2025-03-14T10:35:00.000Z",
    "values": {
      "price": 29.99,
      "availability": "In Stock",
      "lastUpdated": "2025-03-14"
    }
  }
}

Execution Failure

Returns detailed failure information when an execution has failed, including the step that caused the failure and an optional screenshot URL.

GET /api/v1/executions/{executionId}/failure

Response

{
  "data": {
    "failed": true,
    "executionId": "j57exec789abc",
    "failedAt": "2025-03-14T10:32:00.000Z",
    "step": {
      "index": 2,
      "name": "Click checkout"
    },
    "error": {
      "message": "Element not found: #checkout-btn"
    },
    "screenshotUrl": "/api/v1/executions/j57exec789abc/steps/2/screenshot",
    "domAvailable": true
  }
}

Returns null in data if the execution has no failure context (i.e., it succeeded or is still running).

Execution Logs

Returns the raw log output from an execution.

GET /api/v1/executions/{executionId}/logs

Response

{
  "data": {
    "executionId": "j57exec789abc",
    "logs": "[10:30:01] Starting bot...\n[10:30:02] Navigating to..."
  }
}

List Scripts

Returns all script versions for a bot, ordered by version number.

GET /api/v1/bots/{botId}/scripts

Response

{
  "data": [
    {
      "id": "m57script001",
      "version": 3,
      "isActive": true,
      "generatedByLLM": false,
      "createdAt": "2025-03-14T10:00:00.000Z"
    },
    {
      "id": "m57script002",
      "version": 2,
      "isActive": false,
      "generatedByLLM": true,
      "createdAt": "2025-03-12T14:00:00.000Z"
    }
  ]
}

Active Script

Returns the currently active script version, including its full content and parsed steps.

GET /api/v1/bots/{botId}/scripts/active

Response

{
  "data": {
    "id": "m57script001",
    "version": 3,
    "content": "# Python automation script
...",
    "steps": [
      { "id": "step-1", "type": "navigate", "description": "Go to site" }
    ],
    "isActive": true,
    "generatedByLLM": false,
    "createdAt": "2025-03-14T10:00:00.000Z"
  }
}

Update Script

Creates a new script version and sets it as the active script. Requires write permission.

PUT /api/v1/bots/{botId}/scripts

Request body

Field	Type	Required	Description
content	string	Yes	The full Python script content
steps	array		Optional step definitions for UI replay. Each step requires `id`, `type`, and `description` (all strings).

curl -X PUT https://api.hidettp.dev/api/v1/bots/{botId}/scripts \
  -H "Authorization: Bearer bm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Bot automation script
import bot_sdk
bot_sdk.open(\"https://example.com\")",
    "steps": [
      {
        "id": "step-1",
        "type": "navigate",
        "description": "Open target site",
        "url": "https://example.com"
      }
    ]
  }'

Response 201 Created

{
  "data": {
    "id": "m57script003",
    "version": 4,
    "hasSteps": true
  }
}

Get Manifest

Returns the bot's manifest (configuration), which defines its type, runtime, capabilities, and parameters.

GET /api/v1/bots/{botId}/manifest

Response

{
  "data": {
    "id": "n57manifest001",
    "botId": "k57abc123def456",
    "name": "Price Monitor",
    "description": "Extracts competitor pricing data",
    "type": "generic",
    "runtime": "browser",
    "capabilities": {
      "incognito": true,
      "adBlock": true,
      "executionTimeout": 120,
      "xvfbResolution": "1920x1080"
    },
    "parameters": [
      {
        "name": "targetUrl",
        "type": "string",
        "label": "Target URL",
        "required": true
      }
    ],
    "createdAt": "2025-03-10T08:00:00.000Z"
  }
}

Manifest fields reference

Field	Type	Description
type	string	`purchase`, `availability`, or `generic`
runtime	string	`browser` or `http`
capabilities	object	Runtime configuration (see below)
parameters	array	User-supplied parameters for action bots

Capabilities

Capability	Type	Description
incognito	boolean	Run browser in incognito mode
locale	string	Browser locale (e.g. `en-US`)
userAgent	string	Custom User-Agent string
timezone	string	Browser timezone (e.g. `America/New_York`)
geolocation	object	`{ latitude, longitude }`
disableCsp	boolean	Disable Content Security Policy
adBlock	boolean	Enable ad blocking
mobile	boolean	Emulate mobile viewport
proxy	string	Proxy server address
proxyDomains	string[]	Only proxy requests to these domains
xvfbResolution	string	Display resolution (e.g. `1920x1080`)
browserArgs	string[]	Additional browser arguments
executionTimeout	number	Timeout in seconds
captchaSolver	string	CAPTCHA solver integration
proxyProvider	string	Managed proxy provider
useBrowserbase	boolean	Use cloud browser infrastructure

Create / Replace Manifest

Creates a new manifest or completely replaces an existing one. Requires write permission.

PUT /api/v1/bots/{botId}/manifest

Request body

Field	Type	Description
type	string	`purchase`, `availability`, or `generic`
runtime	string	`browser` or `http`
capabilities	object	Runtime capabilities (see table above)
parameters	array	Parameter definitions: each with `name`, `type` (`string`/`number`/`date`), `label`, `required`

Response — 201 if created, 200 if replaced. Returns the full manifest object.

Partial Update Manifest

Partially updates an existing manifest. Only provided fields are changed. Requires write permission.

PATCH /api/v1/bots/{botId}/manifest

Same request body fields as PUT, but all are optional. Returns 400 if the bot has no manifest—use PUT to create one first.

Response — returns the updated manifest object.

Get Schedule

Returns the bot's current schedule configuration.

GET /api/v1/bots/{botId}/schedule

Response

{
  "data": {
    "id": "p57sched001",
    "botId": "k57abc123def456",
    "enabled": true,
    "intervalValue": 30,
    "intervalUnit": "minutes",
    "nextRunAt": "2025-03-14T11:00:00.000Z",
    "lastRunAt": "2025-03-14T10:30:00.000Z",
    "lastExecutionId": "j57exec789abc",
    "createdAt": "2025-03-01T08:00:00.000Z",
    "updatedAt": "2025-03-14T10:30:00.000Z"
  }
}

Create / Update Schedule

Creates or updates a bot's schedule. Requires write permission.

PUT /api/v1/bots/{botId}/schedule

Request body

Field	Type	Required	Description
enabled	boolean	Yes	Whether the schedule is active
intervalValue	number	Yes	Interval value (must be ≥ 1)
intervalUnit	string	Yes	`minutes`, `hours`, or `days`

curl -X PUT https://api.hidettp.dev/api/v1/bots/{botId}/schedule \
  -H "Authorization: Bearer bm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "intervalValue": 30,
    "intervalUnit": "minutes"
  }'

Response — returns the full schedule object.

Delete Schedule

Disables and removes a bot's schedule. Requires write permission.

DELETE /api/v1/bots/{botId}/schedule

Response

{
  "data": {
    "deleted": true
  }
}

REST API Reference

Authentication

Base URL

Response Format

Error Handling

List Bots

Get Bot

Create Bot

Update Bot

Delete Bot

Bot Steps

Latest Extract

Latest Execution

Create Execution

List Executions

Get Execution

Cancel Execution

Execution Steps

Single Step

Step Screenshot

Execution Extract

Execution Failure

Execution Logs

List Scripts

Active Script

Update Script

Get Manifest

Manifest fields reference

Capabilities

Create / Replace Manifest

Partial Update Manifest

Get Schedule

Create / Update Schedule

Delete Schedule

Ready to Build?