BoVerse Documentation

Overview

BoVerse provides three integration options depending on your use case:

REST API

The BoVerse REST API lets you execute workflows, list available workflows, and retrieve execution history. All endpoints require a Bearer token obtained from your BoVerse account settings.

Authentication

All API requests must include an Authorization header with your API key:

Authorization: Bearer YOUR_API_KEY

Generate an API key from your BoVerse account under Settings → API Keys.

Execute Workflow

Runs a workflow with the provided input and returns the result synchronously.

Request Body

{
  "workflow_id": "wf_abc123",
  "query": "Summarize the latest market trends for SaaS companies"
}

Response

{
  "success": true,
  "final_output": "Here are the latest market trends for SaaS companies...",
  "results": [
    {
      "step_id": "step_1",
      "step_name": "Research Agent",
      "output": "Found 12 relevant articles..."
    },
    {
      "step_id": "step_2",
      "step_name": "Summary Writer",
      "output": "Here are the latest market trends for SaaS companies..."
    }
  ]
}

Example

curl -X POST https://python.boverse.io/api/execute-workflow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_abc123",
    "query": "What are the top AI trends in 2025?"
  }'

Poll Execution Status

After triggering a workflow execution, poll this endpoint to check whether the execution has completed, failed, or is still running.

Response

{
  "success": true,
  "status": "running | completed | failed",
  "output_data": "string | null",
  "citations": [],
  "execution_log_id": "uuid-string | null",
  "error_message": "string | null"
}

Example

curl "https://www.boverse.io/api/execution-status?execution_id=YOUR_EXECUTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Poll every 2-5 seconds until status is completed or failed. The execution_id is returned by the Execute Workflow endpoint, and is also available in the status_url field of the execute response.

List Workflows

Returns all workflows accessible to the authenticated user.

curl https://python.boverse.io/api/workflows/list \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Market Research Agent",
      "description": "Researches and summarizes market trends"
    },
    {
      "id": "wf_def456",
      "name": "Email Drafter",
      "description": "Drafts professional emails from bullet points"
    }
  ]
}

Workflow Runs

Retrieves execution history for a specific workflow.

curl "https://python.boverse.io/api/workflows/wf_abc123/runs?limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "runs": [
    {
      "id": "run_xyz789",
      "status": "completed",
      "output": "Here are the latest SaaS trends...",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

MCP Server

The @boverse/mcp package provides a Model Context Protocol server, giving Claude and other MCP-compatible AI assistants direct access to your BoVerse workflows.

Installation

npm install -g @boverse/mcp

Claude Desktop Setup

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "boverse": {
      "command": "npx",
      "args": ["@boverse/mcp"],
      "env": {
        "BOVERSE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Self-hosted deployments can point the server elsewhere with BOVERSE_API_URL. It must be an https URL (plain http is accepted only for localhost).

Available Tools

Example Usage in Claude

Once configured, you can ask Claude to run your workflows directly:

React npm Package

The @boverse/react package provides drop-in React components and hooks for embedding BoVerse workflow execution in your web app.

Installation

npm install @boverse/react

Initialize Client

import { createBoVerseClient } from '@boverse/react';

const client = createBoVerseClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://python.boverse.io', // optional
});

useWorkflow Hook

For custom UI, use the useWorkflow hook directly:

import { useWorkflow, createBoVerseClient } from '@boverse/react';

const client = createBoVerseClient({ apiKey: 'YOUR_API_KEY' });

function WorkflowRunner() {
  const { execute, result, isLoading, error } = useWorkflow(client);

  const handleRun = async () => {
    await execute({
      workflowId: 'wf_abc123',
      query: 'Analyze Q4 2024 sales data',
    });
  };

  return (
    <div>
      <button onClick={handleRun} disabled={isLoading}>
        {isLoading ? 'Running...' : 'Run Workflow'}
      </button>
      {result && <pre>{result.final_output}</pre>}
      {error && <p className="text-red-600">{error}</p>}
    </div>
  );
}

All Exports