REST API Reference
Complete REST API documentation: endpoints, request/response formats, error handling, and code examples for integrating with WorkFlux.
REST API Overview
WorkFlux provides a comprehensive REST API for programmatic access to all platform features. The API follows RESTful principles and uses JSON for data exchange.
Base URL: https://api.workflux.ai/v1
Authentication
All API requests require authentication using OAuth 2.0. See the API Authentication guide for details.
Core Endpoints
Agents Endpoints:
```bash
# List all agents
GET /agents
Query Parameters:
- page: integer (default: 1)
- limit: integer (default: 20, max: 100)
- category: string (filter by category)
- status: string (active, inactive)
# Response:
{
"data": [
{
"id": "agent-123",
"name": "Customer Support Agent",
"category": "Customer Engagement",
"status": "active",
"created_at": "2024-01-01T00:00:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 12,
"total_pages": 1
}
}
# Get agent details
GET /agents/{agent_id}
# Create agent
POST /agents
Content-Type: application/json
{
"name": "Custom Agent",
"category": "Customer Engagement",
"config": {
"personality": "professional",
"language": "en"
}
}
# Update agent
PUT /agents/{agent_id}
Content-Type: application/json
{
"name": "Updated Agent Name",
"config": {
"personality": "friendly"
}
}
# Delete agent
DELETE /agents/{agent_id}
```
Conversations Endpoints:
```bash
# List conversations
GET /conversations
Query Parameters:
- agent_id: string (filter by agent)
- status: string (active, completed, escalated)
- start_date: ISO 8601 date
- end_date: ISO 8601 date
- page: integer
- limit: integer
# Response:
{
"data": [
{
"id": "conv-123",
"agent_id": "agent-123",
"status": "completed",
"started_at": "2024-01-01T10:00:00Z",
"ended_at": "2024-01-01T10:05:00Z",
"messages_count": 8,
"resolution_rate": 1.0
}
]
}
# Get conversation details
GET /conversations/{conversation_id}
# Get conversation messages
GET /conversations/{conversation_id}/messages
# Create conversation
POST /conversations
Content-Type: application/json
{
"agent_id": "agent-123",
"channel": "chat",
"user_id": "user-456",
"initial_message": "Hello, I need help"
}
# Send message
POST /conversations/{conversation_id}/messages
Content-Type: application/json
{
"content": "User message here",
"sender": "user"
}
```
Analytics Endpoints:
```bash
# Get analytics data
GET /analytics
Query Parameters:
- agent_id: string
- metric: string (resolution_rate, response_time, volume)
- start_date: ISO 8601 date
- end_date: ISO 8601 date
- group_by: string (day, week, month)
# Response:
{
"metrics": {
"resolution_rate": 0.85,
"avg_response_time": 1.5,
"total_conversations": 1250,
"total_messages": 8750
},
"time_series": [
{
"date": "2024-01-01",
"resolution_rate": 0.82,
"conversations": 45
}
]
}
# Get agent performance
GET /analytics/agents/{agent_id}
# Get ROI metrics
GET /analytics/roi
```
Integrations Endpoints:
```bash
# List integrations
GET /integrations
# Get integration details
GET /integrations/{integration_id}
# Create integration
POST /integrations
Content-Type: application/json
{
"type": "salesforce",
"name": "Salesforce CRM",
"config": {
"instance_url": "https://na1.salesforce.com",
"access_token": "..."
}
}
# Test integration
POST /integrations/{integration_id}/test
# Sync integration
POST /integrations/{integration_id}/sync
```
Error Handling
The API uses standard HTTP status codes:
• 200 OK - Success
• 201 Created - Resource created
• 400 Bad Request - Invalid request
• 401 Unauthorized - Authentication required
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error
Error Response Format:
```json
{
"error": {
"code": "INVALID_REQUEST",
"message": "The request is missing required fields",
"details": {
"field": "agent_id",
"reason": "required"
},
"request_id": "req_1234567890",
"timestamp": "2024-01-01T12:00:00Z"
}
}
```
Common Error Codes:
• `INVALID_REQUEST` - Request validation failed
• `AUTHENTICATION_FAILED` - Invalid or expired token
• `PERMISSION_DENIED` - Insufficient permissions
• `RESOURCE_NOT_FOUND` - Requested resource doesn't exist
• `RATE_LIMIT_EXCEEDED` - Too many requests
• `INTEGRATION_ERROR` - Integration operation failed
• `VALIDATION_ERROR` - Data validation failed
Rate Limit Headers:
```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704110400
Retry-After: 60
```
Error Handling Best Practices:
```python
import requests
import time
def make_request_with_retry(url, headers, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers)
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
continue
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code >= 500 and attempt < max_retries - 1:
time.sleep(2 attempt) # Exponential backoff
continue
raise
raise Exception('Max retries exceeded')
```
Related
API Authentication & Authorization
Learn OAuth 2.0 authentication, API key management, token refresh, and security best practices for API access.
Webhooks Guide
Set up webhooks to receive real-time notifications from WorkFlux. Configure endpoints, verify signatures, and handle events.
API Rate Limits & Best Practices
Understand API rate limits, implement rate limiting strategies, and optimize API usage for your integration.
Custom Integration Guide
Build custom integrations with WorkFlux API. Connect to proprietary systems, create custom workflows, and extend platform capabilities.