Overview

Complete API reference for integrating with BroxiAI

BroxiAI provides a comprehensive REST API for integrating your workflows into external applications, automating processes, and building custom solutions.

API Architecture

Base URL

All API requests should be made to:

https://api.broxi.ai/v1

Authentication

BroxiAI uses API tokens for authentication. Include your token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Getting Your API Token

Log into your BroxiAI dashboard
Navigate to Settings → API Keys
Generate a new API token
Copy and securely store your token

Keep your API tokens secure and never expose them in client-side code. Tokens have the same permissions as your user account.

Core Endpoints

Workflows

Run a Workflow

Execute a published workflow with input data.

POST /v1/flows/{flow_id}/run

Parameters

flow_id (string, required): The unique identifier of your workflow

Request Body

{
  "input": "Your input message or data",
  "session_id": "optional-session-id",
  "stream": false,
  "variables": {
    "custom_variable": "value"
  }
}

Response

{
  "id": "run_12345",
  "flow_id": "flow_abc123",
  "status": "completed",
  "output": "Generated response from workflow",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z",
  "usage": {
    "total_tokens": 150,
    "prompt_tokens": 100,
    "completion_tokens": 50
  }
}

Stream Workflow Execution

Execute a workflow with real-time streaming response.

POST /v1/flows/{flow_id}/stream

Request Body

{
  "input": "Your input message",
  "session_id": "session_abc123"
}

Response (Server-Sent Events)

data: {"type": "start", "run_id": "run_12345"}

data: {"type": "token", "content": "Hello"}

data: {"type": "token", "content": " world"}

data: {"type": "end", "run_id": "run_12345", "usage": {...}}

Get Workflow Status

Check the status of a running workflow.

GET /v1/runs/{run_id}

Response

{
  "id": "run_12345",
  "flow_id": "flow_abc123",
  "status": "running|completed|failed",
  "progress": 75,
  "output": "Partial or complete output",
  "error": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Flow Management

List Workflows

Get all your published workflows.

GET /v1/flows

Query Parameters

limit (integer): Number of flows to return (default: 20, max: 100)
offset (integer): Number of flows to skip (default: 0)
status (string): Filter by status (published, draft)

Response

{
  "flows": [
    {
      "id": "flow_abc123",
      "name": "Customer Support Bot",
      "description": "AI assistant for customer inquiries",
      "status": "published",
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T14:30:00Z",
      "endpoint": "https://api.broxi.ai/v1/flows/flow_abc123/run"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Get Workflow Details

Retrieve detailed information about a specific workflow.

GET /v1/flows/{flow_id}

Response

{
  "id": "flow_abc123",
  "name": "Customer Support Bot",
  "description": "AI assistant for customer inquiries",
  "status": "published",
  "config": {
    "input_schema": {
      "type": "object",
      "properties": {
        "message": {"type": "string"},
        "user_id": {"type": "string"}
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "response": {"type": "string"},
        "confidence": {"type": "number"}
      }
    }
  },
  "created_at": "2024-01-10T09:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Session Management

Create Session

Create a new conversation session for stateful interactions.

POST /v1/sessions

Request Body

{
  "flow_id": "flow_abc123",
  "user_id": "user_xyz789",
  "metadata": {
    "source": "web_app",
    "version": "1.0"
  }
}

Response

{
  "id": "session_def456",
  "flow_id": "flow_abc123",
  "user_id": "user_xyz789",
  "status": "active",
  "created_at": "2024-01-15T10:00:00Z",
  "metadata": {
    "source": "web_app",
    "version": "1.0"
  }
}

Get Session History

Retrieve conversation history for a session.

GET /v1/sessions/{session_id}/history

Response

{
  "session_id": "session_def456",
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Hello, I need help",
      "timestamp": "2024-01-15T10:00:00Z"
    },
    {
      "id": "msg_002", 
      "role": "assistant",
      "content": "How can I assist you today?",
      "timestamp": "2024-01-15T10:00:05Z"
    }
  ],
  "total": 2
}

Analytics

Get Usage Statistics

Retrieve usage metrics for your workflows.

GET /v1/analytics/usage

Query Parameters

start_date (string): Start date (ISO 8601 format)
end_date (string): End date (ISO 8601 format)
flow_id (string): Filter by specific workflow
granularity (string): Data granularity (hour, day, week, month)

Response

{
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "metrics": {
    "total_runs": 1250,
    "successful_runs": 1180,
    "failed_runs": 70,
    "total_tokens": 125000,
    "avg_response_time": 2.3,
    "cost": 15.75
  },
  "daily_breakdown": [
    {
      "date": "2024-01-01",
      "runs": 45,
      "tokens": 4500,
      "cost": 0.68
    }
  ]
}

Error Handling

The API returns standard HTTP status codes and detailed error messages.

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is invalid",
    "details": {
      "field": "input",
      "reason": "Required field is missing"
    }
  },
  "request_id": "req_abc123"
}

Common Error Codes

Code

Status

Description

INVALID_REQUEST

400

Invalid request format or parameters

UNAUTHORIZED

401

Invalid or missing API token

FORBIDDEN

403

Insufficient permissions

NOT_FOUND

404

Resource not found

RATE_LIMITED

429

Too many requests

INTERNAL_ERROR

500

Server error

SERVICE_UNAVAILABLE

503

Service temporarily unavailable

Rate Limits

API requests are rate limited to ensure fair usage:

Free Tier: 100 requests per minute
Pro Tier: 1,000 requests per minute
Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642694400

Webhooks

Configure webhooks to receive real-time notifications about workflow events.

Webhook Events

flow.run.started: Workflow execution began
flow.run.completed: Workflow execution finished successfully
flow.run.failed: Workflow execution failed
session.created: New session created
session.ended: Session ended

Webhook Payload

{
  "event": "flow.run.completed",
  "data": {
    "run_id": "run_12345",
    "flow_id": "flow_abc123",
    "status": "completed",
    "output": "Generated response",
    "usage": {
      "total_tokens": 150
    }
  },
  "timestamp": "2024-01-15T10:30:05Z"
}

For webhook setup, see Webhook Configuration.

SDKs and Libraries

Official SDKs are available for popular programming languages:

Python SDK

from broxi import BroxiClient

client = BroxiClient(api_token="your_token")

# Run a workflow
result = client.flows.run(
    flow_id="flow_abc123",
    input="Hello, world!"
)
print(result.output)

JavaScript SDK

import { BroxiClient } from '@broxi/sdk';

const client = new BroxiClient({
  apiToken: 'your_token'
});

// Run a workflow
const result = await client.flows.run({
  flowId: 'flow_abc123',
  input: 'Hello, world!'
});
console.log(result.output);

cURL Examples

Basic Workflow Execution

curl -X POST "https://api.broxi.ai/v1/flows/flow_abc123/run" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "What is the weather like today?",
    "variables": {
      "location": "San Francisco"
    }
  }'

Streaming Response

curl -X POST "https://api.broxi.ai/v1/flows/flow_abc123/stream" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "input": "Tell me a story",
    "session_id": "session_123"
  }'

Best Practices

Performance Optimization

Use Sessions: For conversational flows, use sessions to maintain context
Batch Requests: Group multiple operations when possible
Caching: Cache responses for repeated queries
Streaming: Use streaming for long-running operations

Security

Secure Storage: Store API tokens securely
Token Rotation: Rotate tokens regularly
Network Security: Use HTTPS for all requests
Input Validation: Validate all user inputs

Error Handling

Retry Logic: Implement exponential backoff for retries
Circuit Breakers: Prevent cascading failures
Logging: Log API interactions for debugging
Monitoring: Monitor API usage and errors

Support

For API support:

Check our troubleshooting guide
Review code examples
Contact technical support
Join our developer community

PreviousEnvironment Management NextAuthentication

Last updated 4 months ago

hashtagAPI Architecture

hashtagBase URL

hashtagAuthentication

hashtagGetting Your API Token

hashtagCore Endpoints

hashtagWorkflows

hashtagRun a Workflow

hashtagStream Workflow Execution

hashtagGet Workflow Status

hashtagFlow Management

hashtagList Workflows

hashtagGet Workflow Details

hashtagSession Management

hashtagCreate Session

hashtagGet Session History

hashtagAnalytics

hashtagGet Usage Statistics

hashtagError Handling

hashtagError Response Format

hashtagCommon Error Codes

hashtagRate Limits

hashtagWebhooks

hashtagWebhook Events

hashtagWebhook Payload

hashtagSDKs and Libraries

hashtagPython SDK

hashtagJavaScript SDK

hashtagcURL Examples

hashtagBasic Workflow Execution

hashtagStreaming Response

hashtagBest Practices

hashtagPerformance Optimization

hashtagSecurity

hashtagError Handling

hashtagSupport

API Architecture

Base URL

Authentication

Getting Your API Token

Core Endpoints

Workflows

Run a Workflow

Stream Workflow Execution

Get Workflow Status

Flow Management

List Workflows

Get Workflow Details

Session Management

Create Session

Get Session History

Analytics

Get Usage Statistics

Error Handling

Error Response Format

Common Error Codes

Rate Limits

Webhooks

Webhook Events

Webhook Payload

SDKs and Libraries

Python SDK

JavaScript SDK

cURL Examples

Basic Workflow Execution

Streaming Response

Best Practices

Performance Optimization

Security

Error Handling

Support