---
title: "ServiceOS Helpdesk API"
description: "AI-native helpdesk and ticketing API with workflows, SLA management, CSAT, semantic search, and agent analytics"
canonical: "https://docs.ainative.studio/docs/business-ops/serviceos"
last-updated: "2026-10-26T19:08:16.785Z"
---

# ServiceOS Helpdesk API

Source: https://docs.ainative.studio/docs/business-ops/serviceos

> AI-native helpdesk and ticketing API with workflows, SLA management, CSAT, semantic search, and agent analytics

## ServiceOS Helpdesk API

**Base URL:** `https://helpdesk.ainative.studio`  
**API Prefix:** `/api`  
**Auth:** AINative JWT Bearer or API Key (`X-API-Key`)  
**Swagger:** [helpdesk.ainative.studio/api-docs](https://helpdesk.ainative.studio/api-docs)  
**Source:** Private — [AINative-Studio/service-os](https://github.com/AINative-Studio/service-os)

ServiceOS is an AI-native helpdesk API built on ZeroDB. It provides 170+ endpoints covering the full support lifecycle — ticket management, workflow automation, SLA enforcement, CSAT surveys, QA scoring, semantic search, and real-time streaming. Designed for API and MCP consumption — no UI required.

:::tip Health Check
```bash
curl https://helpdesk.ainative.studio/health
## {"status":"ok","timestamp":"2026-06-13T22:26:14.052Z"}
```
:::

---

## Quick Start

### 1. Get an API Key

```bash
curl -X POST https://helpdesk.ainative.studio/api/organizations/YOUR_ORG_ID/api-keys \
  -H "Content-Type: application/json" \
  -H "x-org-id: YOUR_ORG_ID" \
  -H "x-actor-id: admin" \
  -H "x-actor-type: user" \
  -d '{"name":"My App","scopes":["read:tickets","write:tickets"]}'
```

Save the returned key — it's only shown once.

### 2. Create a Ticket

```bash
curl -X POST https://helpdesk.ainative.studio/api/tickets \
  -H "Content-Type: application/json" \
  -H "x-org-id: YOUR_ORG_ID" \
  -H "X-API-Key: sk_your_key_here" \
  -d '{
    "title": "Cannot login to dashboard",
    "description": "User reports 500 error on login page",
    "priority": "high",
    "tags": ["login", "bug"]
  }'
```

### 3. List Tickets

```bash
curl https://helpdesk.ainative.studio/api/tickets \
  -H "x-org-id: YOUR_ORG_ID" \
  -H "X-API-Key: sk_your_key_here"
```

---

## Authentication

ServiceOS supports three auth methods (checked in order):

| Method | Header | Use Case |
|--------|--------|----------|
| **JWT Bearer** | `Authorization: Bearer <jwt>` | Web apps using AINative login |
| **API Key** | `X-API-Key: sk_...` | Server-to-server, MCP agents |
| **Legacy Headers** | `x-org-id` + `x-actor-id` | Backward compatibility |

JWT tokens are obtained from `POST https://api.ainative.studio/v1/auth/login` and cached for 5 minutes.

---

## Core API Endpoints

### Tickets

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/tickets` | List tickets (filter by status, priority) |
| `POST` | `/api/tickets` | Create ticket |
| `GET` | `/api/tickets/:id` | Get ticket by ID |
| `PATCH` | `/api/tickets/:id` | Update ticket status |
| `POST` | `/api/tickets/:id/clone` | Clone a ticket |
| `POST` | `/api/tickets/:id/merge` | Merge duplicate tickets |
| `GET` | `/api/tickets/:id/merge-history` | View merge record |
| `PATCH` | `/api/tickets/:id/classification` | Override AI classification |

### Internal Notes

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/tickets/:id/internal-notes` | Add agent-only note |
| `GET` | `/api/tickets/:id/internal-notes` | List notes |
| `PATCH` | `/api/tickets/:id/internal-notes/:note_id` | Edit note |
| `DELETE` | `/api/tickets/:id/internal-notes/:note_id` | Delete note |

### Teams

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/organizations/:org_id/teams` | Create team |
| `GET` | `/api/organizations/:org_id/teams` | List teams |
| `GET` | `/api/organizations/:org_id/teams/:id` | Get team |
| `PUT` | `/api/organizations/:org_id/teams/:id` | Update team |
| `DELETE` | `/api/organizations/:org_id/teams/:id` | Delete team |

### Queues

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/organizations/:org_id/queues` | Create queue |
| `GET` | `/api/organizations/:org_id/queues` | List queues |
| `POST` | `/api/organizations/:org_id/queues/match` | Find matching queues |

### Views (Saved Filters)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/organizations/:org_id/views` | Create saved view |
| `GET` | `/api/organizations/:org_id/views` | List views |
| `GET` | `/api/organizations/:org_id/views/:id/tickets` | Execute view |
| `GET` | `/api/organizations/:org_id/views/:id/count` | Count matching tickets |

### Webhooks

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/v1/webhooks` | Create webhook subscription |
| `GET` | `/api/v1/webhooks` | List webhooks |
| `PATCH` | `/api/v1/webhooks/:id` | Update webhook |
| `DELETE` | `/api/v1/webhooks/:id` | Delete webhook |
| `POST` | `/api/v1/webhooks/:id/test` | Send test payload |

Webhooks deliver events with HMAC-SHA256 signatures in the `X-ServiceOS-Signature` header. Failed deliveries retry with exponential backoff (1s → 30s → 5m → 30m → 2h → 24h).

### Workflows

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/workflows` | Create workflow |
| `GET` | `/api/workflows` | List workflows |
| `PATCH` | `/api/workflows/:id/enable` | Enable workflow |
| `PATCH` | `/api/workflows/:id/disable` | Disable workflow |

### SLA Policies & Timers

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/sla/policies` | Create SLA policy |
| `GET` | `/api/sla/policies` | List policies |
| `POST` | `/api/sla/timers` | Create timer |
| `POST` | `/api/sla/timers/pause` | Pause timer |
| `POST` | `/api/sla/timers/resume` | Resume timer |
| `POST` | `/api/sla/check-breaches` | Check all active timers |

### CSAT Surveys

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/csat/request` | Send CSAT survey |
| `POST` | `/api/csat/submit` | Submit response |
| `GET` | `/api/csat/analytics` | Aggregated analytics |
| `GET` | `/api/csat/by-dimension` | Breakdown by agent/team |

### Bulk Operations

| Method | Endpoint | Description |
|--------|----------|-------------|
| `PATCH` | `/api/bulk/tickets` | Bulk update (max 100) |
| `DELETE` | `/api/bulk/tickets` | Bulk close |
| `POST` | `/api/bulk/tickets/tag` | Bulk add/remove tags |

Supports `dry_run: true` to validate without executing.

### Custom Fields

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/organizations/:org_id/custom-fields` | Create field schema |
| `GET` | `/api/organizations/:org_id/custom-fields` | List fields |
| `DELETE` | `/api/organizations/:org_id/custom-fields/:id` | Delete field |

Supports types: `text`, `number`, `boolean`, `date`, `dropdown`, `multiselect`, `email`, `url`.

### Agent Presence

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/tickets/:id/presence` | Register viewing |
| `GET` | `/api/tickets/:id/presence` | List viewers |
| `DELETE` | `/api/tickets/:id/presence/:agent_id` | Stop viewing |

In-memory, auto-expires after 5 minutes of inactivity.

### Real-Time SSE

```bash
curl -N https://helpdesk.ainative.studio/api/v1/events/stream?org_id=YOUR_ORG_ID \
  -H "X-API-Key: sk_your_key_here"
```

Events: `ticket.updated`, `ticket.comment.added`, `sla.warning`, `keepalive` (every 30s). Max 100 concurrent connections per org.

---

## AI Features

### Auto-Classification

Tickets are automatically classified on creation using Llama 3.3 70B:

```json
{
  "ai_classification": {
    "topic": "billing",
    "urgency": "high",
    "sentiment": "negative",
    "confidence": 0.92,
    "classified_at": "2026-06-13T10:00:00Z"
  }
}
```

Classification runs async (non-blocking). Override manually via `PATCH /api/tickets/:id/classification`.

### Semantic Search

```bash
curl -X POST https://helpdesk.ainative.studio/api/v1/semantic-search \
  -H "Content-Type: application/json" \
  -H "x-org-id: YOUR_ORG_ID" \
  -d '{"query": "customer cannot access billing portal"}'
```

---

## SDKs

### Node.js / TypeScript

```bash
npm install @serviceos/sdk
```

```typescript
import { ServiceOS } from "@serviceos/sdk";

const client = new ServiceOS({
  apiKey: "sk_...",
  orgId: "org_123",
  baseUrl: "https://helpdesk.ainative.studio",
});

const tickets = await client.tickets.list({ status: "open" });
const ticket = await client.tickets.create({ title: "Bug report", priority: "high" });
await client.tickets.update(ticket.ticket_id, { status: "resolved" });
```

Features: auto-retry on 429/5xx, pagination helpers, TypeScript types, debug mode.

### Python

```bash
pip install serviceos
```

```python
from serviceos import ServiceOS

client = ServiceOS(api_key="sk_...", org_id="org_123")

tickets = client.tickets.list(status="open")
ticket = client.tickets.create(title="Bug report", priority="high")
```

Features: sync + async, Pydantic models, auto-retry with tenacity.

### Go

```go
import serviceos "github.com/AINative-Studio/serviceos-go"

client := serviceos.NewClient("sk_...",
    serviceos.WithOrgID("org_123"),
    serviceos.WithBaseURL("https://helpdesk.ainative.studio"),
)

tickets, _ := client.Tickets.List(ctx, &serviceos.ListTicketsParams{Status: "open"})
```

Features: context-aware, auto-retry, pagination iterator, zero external deps.

---

## MCP Server

Connect ServiceOS to AI agents via the Model Context Protocol:

```json
{
  "mcpServers": {
    "serviceos": {
      "command": "npx",
      "args": ["@serviceos/mcp-server"],
      "env": {
        "SERVICEOS_API_KEY": "sk_...",
        "SERVICEOS_ORG_ID": "org_123",
        "SERVICEOS_BASE_URL": "https://helpdesk.ainative.studio"
      }
    }
  }
}
```

### Available Tools

| Tool | Description |
|------|-------------|
| `serviceos_list_tickets` | List tickets with filters |
| `serviceos_get_ticket` | Get ticket details |
| `serviceos_create_ticket` | Create a ticket |
| `serviceos_update_ticket` | Update status/priority |
| `serviceos_list_teams` | List teams |
| `serviceos_list_queues` | List queues |
| `serviceos_search_tickets` | Semantic search |
| `serviceos_get_agent_stats` | Agent performance |
| `serviceos_list_sla_breaches` | Breached SLA timers |
| `serviceos_create_internal_note` | Add agent note |

---

## Rate Limiting

All endpoints return standard rate limit headers:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1718323200
```

| Tier | Limit | Window |
|------|-------|--------|
| General API | 1000 req | Per hour |
| Auth endpoints | 20 req | Per minute |
| Bulk operations | 10 req | Per minute |

Exceeding limits returns `429 Too Many Requests` with `Retry-After` header.

---

## Data Model

### Ticket

```typescript
interface Ticket {
  ticket_id: string;       // Unique ID (ZeroDB row_id)
  org_id: string;          // Organization
  title: string;
  status: "new" | "open" | "pending" | "on_hold" | "resolved" | "closed" | "merged";
  priority: "low" | "normal" | "high" | "urgent";
  customer_id: string;
  team_id?: string;
  queue_id?: string;
  assignee_user_id?: string;
  tags: string[];
  ai_classification?: {
    topic: string;
    urgency: string;
    sentiment: string;
    confidence: number;
  };
  created_at: string;      // ISO 8601
  updated_at: string;
}
```

### Webhook Event Topics

| Topic | Fired When |
|-------|------------|
| `ticket.created` | New ticket created |
| `ticket.updated` | Ticket fields changed |
| `ticket.status.changed` | Status transition |
| `ticket.linked` | Parent-child link created |
| `sla.breached` | SLA timer breached |
| `ai.triage.completed` | AI classification done |

---

## Full API Reference

See the interactive Swagger documentation at:

**[helpdesk.ainative.studio/api-docs](https://helpdesk.ainative.studio/api-docs)**

124 documented endpoints with request/response schemas, try-it-out capability, and example payloads.

---

## Admin Dashboard Integration

ServiceOS is integrated into the AINative admin dashboard at `/live-chat` with a 7-tab super admin console:

| Tab | ServiceOS Endpoints | Status |
|-----|---------------------|--------|
| **Conversations** | `/tickets`, `/public/chat` | Live — search, filters, internal notes, macros |
| **Analytics** | `/agent-statistics`, `/trends` | Live — KPIs, agent performance, volume trends |
| **Teams** | `/teams` (7), `/queues` (6), `/routing` | API live; admin dashboard tab in progress |
| **SLA** | `/sla` (13), `/sla-breach-workflow` (9) | Live — policy list by priority |
| **CSAT** | `/csat` (5) | Live — score, ratings, feedback |
| **Macros** | `/macros` (9) | Live — library, insert into reply |
| **Settings** | config, channels, AI | Live — inbox token, embed code, status |

### Chat Widget

The embeddable chat widget (`ServiceOSChatWidget`) is powered by the public visitor API:

```
POST /api/v1/public/serviceos/conversations  — start chat (inbox_token scoped)
GET  /api/v1/public/serviceos/conversations/{id}/messages — get messages
POST /api/v1/public/serviceos/conversations/{id}/messages — send message
GET  /api/v1/public/serviceos/conversations/{id}/stream   — SSE real-time
POST /api/v1/public/serviceos/conversations/{id}/typing   — typing indicator
```

AI auto-reply powered by AINative chat completions (llama-3.3-8b-instruct).

### Phase 2 Roadmap

| Feature | Issues | ServiceOS Endpoints |
|---------|--------|---------------------|
| Workflow automation | [#4223](https://github.com/AINative-Studio/core/issues/4223) | `/workflows` (8) |
| Custom ticket fields | [#4224](https://github.com/AINative-Studio/core/issues/4224) | `/custom-fields` (5) |
| Bulk operations | [#4225](https://github.com/AINative-Studio/core/issues/4225) | `/bulk` (3) |
| Import/export | [#4226](https://github.com/AINative-Studio/core/issues/4226) | `/import` (5) |
| Audit log viewer | [#4227](https://github.com/AINative-Studio/core/issues/4227) | `/audit-logs` (6) |
| Translation management | [#4228](https://github.com/AINative-Studio/core/issues/4228) | `/translations` (7) |
| QA rubric scoring | [#4229](https://github.com/AINative-Studio/core/issues/4229) | `/qa-rubrics` (9) + `/ticket-qa` (2) |
| Webhook configuration | [#4230](https://github.com/AINative-Studio/core/issues/4230) | `/webhooks` (6) |
| Channel setup wizard | [#4231](https://github.com/AINative-Studio/core/issues/4231) | `/channels` (3) |