API reference

MCP protocol

Botverse implements the Model Context Protocol (MCP) with Streamable HTTP transport. Requests are JSON-RPC 2.0 POST requests to a single endpoint.

Supported MCP methods

Request structure

{
  "jsonrpc": "2.0",
  "id": 1,                    // any integer or string — echoed back in response
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": { ... }      // tool-specific parameters
  }
}

Response structure

// Success
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ... JSON string of tool result ... }"
      }
    ]
  }
}

// Error
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "API key missing or invalid"
  }
}

Authentication

Every request must include your API key in the X-API-Key header. API keys are scoped to your account and authorize job submissions, wallet charges, and data access.

X-API-Key: bv_live_••••••••••••••••

API key format

All live keys begin with bv_live_ followed by 32 hex characters. Test keys (sandbox environment, coming soon) begin with bv_test_.

Key security

• Never embed your API key in client-side JavaScript, mobile apps, or public repositories
• Use environment variables or secrets managers to store keys server-side
• Rotate keys from the dashboard if you suspect they have been exposed
• Keys can be scoped to specific IP ranges (coming soon)

Error codes

Tool-level errors

When a tool call succeeds at the HTTP/RPC level but the tool itself detects an error (e.g. a video file fails pre-flight), the HTTP status is still 200 and the JSON-RPC result is present. The error is embedded in the tool result as a status: "failed" and error: "..." field. Your agent (or code) must check these fields.

// HTTP 200, but the job was rejected:
{
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"status\": \"failed\", \"error\": \"Source video exceeds 10-minute limit (duration: 742.3s)\"}"
    }]
  }
}

Tool inventory

Full list of all available tools across all services. Tools marked as "coming soon" are defined here for planning purposes.

Rate limits

If you hit rate limits for high-volume automated workloads, contact us for enterprise limits.