Skip to content
SupportOS
Back to Docs

API Reference

REST API documentation for SupportOS. All endpoints return JSON.

Authentication

The /api/v1 endpoints require your workspace API key as a bearer token in the Authorization header. Dashboard endpoints use the signed-in session cookie.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Widget endpoints (/api/widget/*) do not require authentication — they are public by design.

Base URL

https://support-app.blueforge.studio

Endpoints

POST/api/widget/message

Submit a message from the widget. Creates a conversation if none exists for the visitor.

Request Body

{
  "workspaceId": "ws_abc123",
  "visitorEmail": "user@example.com",
  "visitorName": "Jane Doe",
  "message": "How do I reset my password?"
}

Response

{
  "conversationId": "conv_xyz789",
  "messageId": "msg_001",
  "status": "open",
  "createdAt": "2026-04-04T12:00:00Z"
}
GET/api/widget?org=ID

Get widget configuration for a workspace. Used by the widget script on initialization.

Response

{
  "workspaceId": "ws_abc123",
  "workspaceName": "Acme Corp",
  "accentColor": "#2563eb",
  "greeting": "Hi there! How can we help?",
  "title": "Acme Support"
}
GET/api/conversationsAuth Required

List conversations for the authenticated workspace. Supports pagination and status filtering.

Response

{
  "data": [
    {
      "id": "conv_xyz789",
      "subject": "Password reset",
      "status": "open",
      "priority": "normal",
      "channel": "chat",
      "assigneeId": null,
      "createdAt": "2026-04-04T12:00:00Z",
      "updatedAt": "2026-04-04T12:05:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 42
}
POST/api/conversationsAuth Required

Create a new conversation.

Request Body

{
  "subject": "Billing question",
  "channel": "email",
  "priority": "normal",
  "customerEmail": "user@example.com",
  "customerName": "Jane Doe"
}

Response

{
  "id": "conv_new001",
  "subject": "Billing question",
  "status": "open",
  "priority": "normal",
  "channel": "email",
  "createdAt": "2026-04-04T14:00:00Z"
}
GET/api/messages?conversationId=IDAuth Required

Get all messages in a conversation, ordered chronologically.

Response

{
  "data": [
    {
      "id": "msg_001",
      "conversationId": "conv_xyz789",
      "body": "How do I reset my password?",
      "sender": "customer",
      "createdAt": "2026-04-04T12:00:00Z"
    },
    {
      "id": "msg_002",
      "conversationId": "conv_xyz789",
      "body": "You can reset it at Settings > Security > Change Password.",
      "sender": "agent",
      "createdAt": "2026-04-04T12:03:00Z"
    }
  ]
}
POST/api/messagesAuth Required

Send a message in a conversation.

Request Body

{
  "conversationId": "conv_xyz789",
  "body": "Here are the steps to reset your password...",
  "sender": "agent"
}

Response

{
  "id": "msg_003",
  "conversationId": "conv_xyz789",
  "body": "Here are the steps to reset your password...",
  "sender": "agent",
  "createdAt": "2026-04-04T12:10:00Z"
}
GET/api/articlesAuth Required

List published knowledge base articles. Supports search query parameter.

Response

{
  "data": [
    {
      "id": "art_001",
      "title": "How to reset your password",
      "slug": "reset-password",
      "excerpt": "Step-by-step guide to resetting your account password.",
      "status": "published",
      "createdAt": "2026-03-15T10:00:00Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 5
}
POST/api/ai/triageAuth Required

AI-triage a conversation. Returns suggested category, priority, and assignee.

Request Body

{
  "conversationId": "conv_xyz789"
}

Response

{
  "conversationId": "conv_xyz789",
  "suggestions": {
    "category": "account",
    "priority": "normal",
    "assigneeId": "agent_002",
    "confidence": 0.92
  }
}
POST/api/ai/reply-suggestionsAuth Required

Get AI-generated reply suggestions for a conversation. Returns up to 3 draft replies.

Request Body

{
  "conversationId": "conv_xyz789"
}

Response

{
  "conversationId": "conv_xyz789",
  "suggestions": [
    {
      "body": "You can reset your password by going to Settings > Security > Change Password. Let me know if you need further help!",
      "confidence": 0.95,
      "source": "kb_article:art_001"
    }
  ]
}

Rate Limits

API requests are rate-limited per workspace:

  • Free plan: 60 requests/minute
  • Starter/Team: 300 requests/minute
  • Business: 1,000 requests/minute

Rate-limited responses return HTTP 429 Too Many Requests with a Retry-After header.

← Widget ReferenceAll Docs →