Support-OS API v1

A tenant-scoped REST API for tickets. All responses are JSON.

Base URL: https://app.sevakdesk.com/api/v1

Authentication

Every request needs a personal API token, passed as a Bearer header. Generate one under Admin → API Tokens (shown once). Requests act as your account and only ever see your workspace's data.

Authorization: Bearer sos_your_token_here
Accept: application/json

Scopes

A token only does what it was issued for. Choose the narrowest set that works — a reporting key needs tickets:read and nothing else. Calling an endpoint your token lacks the scope for returns 403 naming the scope required.

tickets:read Read tickets
tickets:write Create and update tickets
records:read Read records
records:write Create records

A scope never widens access. Your role still applies on top — a customer's token with tickets:write can still only raise their own tickets.

Endpoint reference

Every endpoint, with the role and scope it requires. Worked examples follow below.

Endpoint Role Scope
GET /api/v1/commands any any token
POST /api/v1/commands/execute any tickets:write
GET /api/v1/entities admin records:read
POST /api/v1/entities admin records:write
GET /api/v1/me any any token
GET /api/v1/tickets any tickets:read
POST /api/v1/tickets customer tickets:write
GET /api/v1/tickets/{id} any tickets:read
PATCH /api/v1/tickets/{id} agent,admin tickets:write
GET /me

The account the token belongs to.

curl https://app.sevakdesk.com/api/v1/me \
  -H "Authorization: Bearer <token>" -H "Accept: application/json"

200 Response

{ "data": { "id": 6, "name": "System Admin", "email": "admin@acme.com", "role": "admin", "tenant_id": 1, "tenant": "Acme Corp" } }
GET /tickets

List tickets (paginated). Customers see only their own; agents and admins see the whole workspace.

Query parameters

Param Type Description
status string Filter: RECEIVED · INVESTIGATING · RESOLVED · CLOSED
priority string Filter: LOW · MEDIUM · HIGH · URGENT
per_page int Page size (max 100, default 20)
page int Page number
curl "https://app.sevakdesk.com/api/v1/tickets?status=RECEIVED&per_page=10" \ -H "Authorization: Bearer <token>" -H "Accept: application/json"

200 Response

{ "data": [ { "id": 12, "ticket_number": "TCK-10590", "status": "RESOLVED", "priority": "MEDIUM", "issue_category": "Link Down", "customer": { "id": 1, "name": "Enet Solutions" }, "assigned_agent_id": 3, "sla_deadline_at": "2026-07-16T12:02:00+00:00", "created_at": "2026-07-18T09:00:00+00:00" } ], "meta": { "current_page": 1, "last_page": 1, "per_page": 10, "total": 2 } }
POST /tickets

Create a ticket. It is routed to the department/tier configured for the category, and an SLA deadline is set.

Body

Field Required Description
issue_category yes Category name (routes the ticket)
description no Free text
priority no LOW · MEDIUM · HIGH · URGENT (default MEDIUM)
curl -X POST https://app.sevakdesk.com/api/v1/tickets \ -H "Authorization: Bearer <token>" -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"issue_category":"Link Down","description":"No signal","priority":"HIGH"}'

201 Response

{ "data": { "id": 42, "ticket_number": "TCK-10601", "status": "RECEIVED", "priority": "HIGH", "issue_category": "Link Down", ... } }
GET /tickets/{id}

Fetch a single ticket. 404 if it isn't in your workspace (or not yours, for customers).

curl https://app.sevakdesk.com/api/v1/tickets/42 \ -H "Authorization: Bearer <token>" -H "Accept: application/json"
PATCH /tickets/{id}

Update a ticket. Agents and admins only. Status changes are validated against the lifecycle state machine — an illegal transition returns 422.

Body (any subset)

Field Description
status RECEIVED · INVESTIGATING · RESOLVED · CLOSED (must be a legal transition)
priority LOW · MEDIUM · HIGH · URGENT
assigned_agent_id Agent user id, or null to unassign
curl -X PATCH https://app.sevakdesk.com/api/v1/tickets/42 \ -H "Authorization: Bearer <token>" -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"status":"INVESTIGATING"}'

Errors

Status Meaning
401 Missing or invalid API token
403 Account inactive, workspace suspended, or action not allowed for your role
404 Resource not found in your workspace
422 Validation error or illegal ticket-status transition

Error bodies are { "message": "..." } (with an errors object for 422 validation failures).