API Reference

The BOSS Platform provides a comprehensive RESTful API for all platform operations. This reference covers authentication, endpoints, data models, and integration patterns.

Base URL

Production: https://api.your-domain.com/v1
Staging: https://staging-api.your-domain.com/v1
Development: http://localhost:3000/api/v1

Authentication

JWT Authentication Flow

Authentication Endpoints

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response 200:
{
  "accessToken": "eyJhbGciOiJ...",
  "refreshToken": "eyJhbGciOiJ...",
  "expiresIn": 900,
  "user": {
    "id": "usr_123",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "admin"
  }
}

Refresh Token

POST /auth/refresh
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJ..."
}

Response 200:
{
  "accessToken": "eyJhbGciOiJ...",
  "expiresIn": 900
}

Core API Endpoints

Tickets API

List Tickets

GET /tickets?status=open&priority=high&page=1&limit=20
Authorization: Bearer {token}

Response 200:
{
  "data": [
    {
      "id": "tkt_123",
      "ticketNumber": "TKT-2024-001",
      "title": "Customer onboarding issue",
      "status": "open",
      "priority": "high",
      "assignedTo": "usr_456",
      "department": "customer-success",
      "createdAt": "2024-01-15T10:00:00Z",
      "tasks": [...]
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}

Create Ticket

POST /tickets
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "New customer request",
  "description": "Details about the request...",
  "priority": "medium",
  "department": "sales",
  "assignedTo": "usr_789",
  "workflowId": "wf_sales_001",
  "customFields": {
    "customerName": "Acme Corp",
    "dealValue": 50000
  }
}

Response 201:
{
  "id": "tkt_124",
  "ticketNumber": "TKT-2024-002",
  "status": "open",
  "createdAt": "2024-01-15T14:30:00Z"
}

Update Ticket

PATCH /tickets/{ticketId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "in-progress",
  "priority": "high",
  "assignedTo": "usr_999"
}

Response 200:
{
  "id": "tkt_124",
  "status": "in-progress",
  "updatedAt": "2024-01-15T15:00:00Z"
}

Workflows API

List Workflows

GET /workflows?department=sales&isActive=true
Authorization: Bearer {token}

Response 200:
{
  "data": [
    {
      "id": "wf_001",
      "name": "Sales Pipeline",
      "department": "sales",
      "isActive": true,
      "phases": [
        {
          "id": "ph_001",
          "name": "Lead Qualification",
          "order": 1,
          "estimatedDuration": 48,
          "tasks": []
        }
      ]
    }
  ]
}

Create Workflow Instance

POST /workflows/{workflowId}/instances
Authorization: Bearer {token}
Content-Type: application/json

{
  "ticketId": "tkt_124",
  "context": {
    "customer": "Acme Corp",
    "value": 50000
  }
}

Response 201:
{
  "id": "wfi_001",
  "workflowId": "wf_001",
  "ticketId": "tkt_124",
  "currentPhase": "ph_001",
  "status": "active",
  "startedAt": "2024-01-15T15:30:00Z"
}

Tasks API

Create Task

POST /tasks
Authorization: Bearer {token}
Content-Type: application/json

{
  "title": "Schedule demo call",
  "description": "Arrange product demo with client",
  "ticketId": "tkt_124",
  "phaseId": "ph_002",
  "assignedTo": "usr_789",
  "dueDate": "2024-01-20T14:00:00Z",
  "priority": "high",
  "estimatedMinutes": 60
}

Response 201:
{
  "id": "tsk_001",
  "status": "pending",
  "createdAt": "2024-01-15T16:00:00Z"
}

Update Task Status

PATCH /tasks/{taskId}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "completed",
  "completedAt": "2024-01-16T10:00:00Z",
  "actualMinutes": 45,
  "notes": "Demo went well, client interested"
}

Response 200:
{
  "id": "tsk_001",
  "status": "completed",
  "completedAt": "2024-01-16T10:00:00Z"
}

Dashboard API

Get Dashboard Configuration

GET /dashboards/{dashboardId}
Authorization: Bearer {token}

Response 200:
{
  "id": "dash_001",
  "name": "Sales Overview",
  "department": "sales",
  "widgets": [
    {
      "id": "w_001",
      "type": "kpi",
      "position": { "x": 0, "y": 0 },
      "size": { "width": 3, "height": 2 },
      "config": {
        "metric": "activeDeals",
        "refreshRate": 30000
      }
    }
  ],
  "layout": "responsive",
  "isPublic": false
}

Update Dashboard

PUT /dashboards/{dashboardId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Updated Sales Dashboard",
  "widgets": [...],
  "layout": "fixed"
}

Response 200:
{
  "id": "dash_001",
  "updatedAt": "2024-01-15T17:00:00Z"
}

GraphQL API

Schema Overview

type Query {
  tickets(
    status: TicketStatus
    priority: Priority
    department: String
    page: Int
    limit: Int
  ): TicketConnection!
  
  ticket(id: ID!): Ticket
  
  workflows(
    department: String
    isActive: Boolean
  ): [Workflow!]!
  
  dashboards: [Dashboard!]!
  
  currentUser: User
}

type Mutation {
  createTicket(input: CreateTicketInput!): Ticket!
  updateTicket(id: ID!, input: UpdateTicketInput!): Ticket!
  
  createTask(input: CreateTaskInput!): Task!
  updateTaskStatus(id: ID!, status: TaskStatus!): Task!
  
  startWorkflow(
    workflowId: ID!
    ticketId: ID!
  ): WorkflowInstance!
}

type Subscription {
  ticketUpdated(id: ID!): Ticket!
  taskStatusChanged(ticketId: ID!): Task!
  dashboardUpdated(id: ID!): Dashboard!
}

GraphQL Query Examples

Query Tickets with Tasks

query GetTicketsWithTasks {
  tickets(status: OPEN, limit: 10) {
    edges {
      node {
        id
        ticketNumber
        title
        status
        priority
        tasks {
          id
          title
          status
          assignedTo {
            name
            email
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Create Ticket Mutation

mutation CreateTicket($input: CreateTicketInput!) {
  createTicket(input: $input) {
    id
    ticketNumber
    status
    workflow {
      id
      name
      currentPhase {
        name
      }
    }
  }
}

variables:
{
  "input": {
    "title": "New customer inquiry",
    "priority": "HIGH",
    "department": "sales",
    "workflowId": "wf_001"
  }
}

WebSocket API

Connection

const ws = new WebSocket('wss://api.your-domain.com/ws');

ws.onopen = () => {
  // Authenticate
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'your_jwt_token'
  }));
  
  // Subscribe to events
  ws.send(JSON.stringify({
    type: 'subscribe',
    channels: ['tickets', 'tasks', 'dashboard']
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  switch(data.type) {
    case 'ticket_updated':
      handleTicketUpdate(data.payload);
      break;
    case 'task_created':
      handleNewTask(data.payload);
      break;
    case 'dashboard_refresh':
      refreshDashboard(data.payload);
      break;
  }
};

Event Types

interface WebSocketEvent {
  type: 'ticket_updated' | 'task_created' | 'workflow_transitioned' | 'dashboard_refresh';
  payload: any;
  timestamp: string;
  userId?: string;
}

Error Handling

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "timestamp": "2024-01-15T18:00:00Z",
    "requestId": "req_abc123"
  }
}

Common Error Codes

Code	HTTP Status	Description
`AUTH_REQUIRED`	401	Authentication required
`INVALID_TOKEN`	401	Invalid or expired token
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Input validation failed
`RATE_LIMITED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error

Rate Limiting

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1642255200
Retry-After: 3600

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 3600 seconds."
  }
}

Pagination

Cursor-based Pagination

GET /tickets?after=cursor_xyz&limit=20

Response:
{
  "data": [...],
  "pageInfo": {
    "hasNextPage": true,
    "hasPreviousPage": true,
    "startCursor": "cursor_abc",
    "endCursor": "cursor_def"
  }
}

Offset-based Pagination

GET /tickets?page=2&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 145,
    "pages": 8
  }
}

Webhooks

Webhook Configuration

POST /webhooks
Authorization: Bearer {token}
Content-Type: application/json

{
  "url": "https://your-app.com/webhook",
  "events": ["ticket.created", "ticket.updated", "task.completed"],
  "secret": "webhook_secret_key"
}

Response 201:
{
  "id": "wh_001",
  "url": "https://your-app.com/webhook",
  "events": ["ticket.created", "ticket.updated", "task.completed"],
  "isActive": true,
  "createdAt": "2024-01-15T19:00:00Z"
}

Webhook Payload

{
  "event": "ticket.created",
  "timestamp": "2024-01-15T19:30:00Z",
  "data": {
    "id": "tkt_125",
    "ticketNumber": "TKT-2024-003",
    "title": "New ticket created"
  },
  "signature": "sha256=abc123..."
}

SDK Examples

JavaScript/TypeScript SDK

import { DashboardAPI } from '@your-org/dashboard-sdk';

const api = new DashboardAPI({
  baseURL: 'https://api.your-domain.com',
  apiKey: 'your_api_key'
});

// Create ticket
const ticket = await api.tickets.create({
  title: 'New request',
  priority: 'high',
  department: 'sales'
});

// List workflows
const workflows = await api.workflows.list({
  department: 'sales',
  isActive: true
});

// Subscribe to updates
api.subscribe('ticket.updated', (event) => {
  console.log('Ticket updated:', event.data);
});

Next Steps

Architecture Overview - System architecture
Getting Started - Development setup
Workflow Management - Understanding workflows
Dashboard System - Dashboard customization

Base URL​

Authentication​

JWT Authentication Flow​

Authentication Endpoints​

Login​

Refresh Token​

Core API Endpoints​

Tickets API​

List Tickets​

Create Ticket​

Update Ticket​

Workflows API​

List Workflows​

Create Workflow Instance​

Tasks API​

Create Task​

Update Task Status​

Dashboard API​

Get Dashboard Configuration​

Update Dashboard​

GraphQL API​

Schema Overview​

GraphQL Query Examples​

Query Tickets with Tasks​

Create Ticket Mutation​

WebSocket API​

Connection​

Event Types​

Error Handling​

Error Response Format​

Common Error Codes​

Rate Limiting​

Pagination​

Cursor-based Pagination​

Offset-based Pagination​

Webhooks​

Webhook Configuration​

Webhook Payload​

SDK Examples​

JavaScript/TypeScript SDK​

Next Steps​

Base URL

Authentication

JWT Authentication Flow

Authentication Endpoints

Login

Refresh Token

Core API Endpoints

Tickets API

List Tickets

Create Ticket

Update Ticket

Workflows API

List Workflows

Create Workflow Instance

Tasks API

Create Task

Update Task Status

Dashboard API

Get Dashboard Configuration

Update Dashboard

GraphQL API

Schema Overview

GraphQL Query Examples

Query Tickets with Tasks

Create Ticket Mutation

WebSocket API

Connection

Event Types

Error Handling

Error Response Format

Common Error Codes

Rate Limiting

Pagination

Cursor-based Pagination

Offset-based Pagination

Webhooks

Webhook Configuration

Webhook Payload

SDK Examples

JavaScript/TypeScript SDK

Next Steps