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
Source: Private — 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.

Health Check

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

---

Quick Start

1. Get an API Key

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

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

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

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:

{
  "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

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

npm install @serviceos/sdk

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

pip install serviceos

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

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:

{
  "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

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

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