ITSM

ITSM Core

Incidents, changes, problems, CMDB, SLA, service catalog, and knowledge base — full ITIL-aligned API reference.

Overview

FlowOS ITSM implements the core ITIL 4 service management processes. Every ITSM record is backed by a DB Studio table and exposed via a typed REST API. ITSM records trigger workflow events, generate audit log entries, and participate in SLA tracking automatically when created.

Incidents

Incidents represent unplanned service disruptions. They have a severity (P1–P4), status lifecycle, assignment, linked CMDB items, and participate in SLA tracking.

GET

/api/v1/itsm/incidents

List incidents with filtering by severity, status, team

POST

/api/v1/itsm/incidents

Create a new incident

GET

/api/v1/itsm/incidents/:id

Get incident detail with timeline

PATCH

/api/v1/itsm/incidents/:id

Update incident fields

POST

/api/v1/itsm/incidents/:id/resolve

Resolve incident (triggers resolved event)

POST

/api/v1/itsm/incidents/:id/escalate

Escalate severity or reassign team

POST

/api/v1/itsm/incidents/:id/comments

Add a timeline comment or work note

POST

/api/v1/itsm/incidents/:id/link

Link to a problem, change, or CMDB item

Create an incident

bash

POST /api/v1/itsm/incidents
{
  "title": "API gateway latency spike — p99 > 5s",
  "description": "Observed at 09:30 UTC. API gateway reporting p99 latency at 5.4s. Affecting checkout and search services.",
  "severity": "P1",
  "category": "infrastructure",
  "impactedServices": ["checkout", "search"],
  "assignedTeam": "infrastructure",
  "assignedTo": "usr_alice",
  "cmdbItems": ["ci_api_gateway_01"],
  "tags": ["latency", "production"],
  "source": "monitoring"       // "monitoring" | "user_report" | "api" | "workflow"
}

Incident schema

Field	Type	Required	Default	Description
id	string	required	—	Unique ID (inc_...)
number	string	optional	—	Human-readable number (INC-1042)
title	string	required	—	Short description of the incident
severity	enum	required	—	P1 \| P2 \| P3 \| P4
status	enum	optional	open	open \| investigating \| identified \| monitoring \| resolved \| closed
assignedTeam	string	optional	—	Team slug responsible for resolution
assignedTo	string	optional	—	User ID of the assigned engineer
impactedServices	string[]	optional	—	List of impacted service names or IDs
cmdbItems	string[]	optional	—	CMDB configuration item IDs related to this incident
relatedProblems	string[]	optional	—	Linked problem IDs
relatedChanges	string[]	optional	—	Linked change IDs (potential root cause)
sla	object	optional	—	SLA state: { policy, dueAt, breached, remainingMs }
resolvedAt	timestamp	optional	—	Set when status transitions to resolved
rootCause	string	optional	—	Root cause description (filled on resolution)

Incident events

These events fire on the platform event bus and can trigger workflows:

•incident.created — New incident opened
•incident.updated — Any field changed
•incident.escalated — Severity raised or team changed
•incident.resolved — Status set to resolved
•incident.sla_breached — SLA deadline passed without resolution
•incident.comment_added — New timeline entry added

Change Management

Changes represent planned modifications to IT infrastructure or services. They have an approval workflow (CAB), a risk assessment, and a rollback plan.

GET

/api/v1/itsm/changes

List change requests

POST

/api/v1/itsm/changes

Create a change request

GET

/api/v1/itsm/changes/:id

Get change detail with approvals and timeline

PATCH

/api/v1/itsm/changes/:id

Update change fields

POST

/api/v1/itsm/changes/:id/submit

Submit for CAB review

POST

/api/v1/itsm/changes/:id/approve

Approve the change (CAB member)

POST

/api/v1/itsm/changes/:id/reject

Reject the change with a reason

POST

/api/v1/itsm/changes/:id/implement

Mark implementation started

POST

/api/v1/itsm/changes/:id/complete

Mark change completed

POST

/api/v1/itsm/changes/:id/rollback

Mark change rolled back

bash

POST /api/v1/itsm/changes
{
  "title": "Upgrade PostgreSQL from 15 to 16 on prod-db-01",
  "type": "normal",              // "standard" | "normal" | "emergency"
  "category": "database",
  "risk": "medium",              // "low" | "medium" | "high" | "critical"
  "impact": "medium",
  "description": "Version upgrade to gain performance improvements and security patches.",
  "implementationPlan": "1. Take snapshot. 2. Stop app servers. 3. Upgrade PG. 4. Run health checks. 5. Restart app servers.",
  "rollbackPlan": "Restore from pre-upgrade snapshot. ETA: 20 minutes.",
  "testPlan": "Run query performance benchmarks before and after. Validate replication.",
  "scheduledStart": "2026-06-15T02:00:00Z",
  "scheduledEnd":   "2026-06-15T04:00:00Z",
  "assignedTeam": "database",
  "cabReviewers": ["usr_dba_lead", "usr_platform_mgr"]
}

Problem Management

GET

/api/v1/itsm/problems

List problems

POST

/api/v1/itsm/problems

Create a problem record

PATCH

/api/v1/itsm/problems/:id

Update problem fields

POST

/api/v1/itsm/problems/:id/known-error

Mark as known error with workaround

POST

/api/v1/itsm/problems/:id/resolve

Resolve the problem

GET

/api/v1/itsm/known-errors

List all known errors with workarounds

SLA Management

SLA policies define response and resolution time targets per severity/category. FlowOS automatically calculates SLA deadlines and fires breach events when thresholds are crossed.

GET

/api/v1/itsm/sla-policies

List SLA policies

POST

/api/v1/itsm/sla-policies

Create an SLA policy

GET

/api/v1/itsm/incidents/:id/sla

Get SLA status for an incident

bash

POST /api/v1/itsm/sla-policies
{
  "name": "Enterprise P1 SLA",
  "appliesTo": { "entityType": "incident", "severity": "P1" },
  "businessHours": {
    "timezone": "America/New_York",
    "schedule": "24x7"           // "24x7" | "business_hours" | custom schedule id
  },
  "targets": {
    "firstResponse": { "hours": 0.25 },   // 15 minutes
    "resolution":    { "hours": 1 }
  },
  "escalations": [
    { "at": "50%",  "action": "notify",   "notify": ["assigned_team_lead"] },
    { "at": "75%",  "action": "escalate", "escalateTo": "incident_manager" },
    { "at": "100%", "action": "breach",   "triggerWorkflow": "wf_sla_breach_response" }
  ]
}

CMDB

The Configuration Management Database stores configuration items (CIs) — hardware, software, services, and relationships between them.

GET

/api/v1/cmdb/items

List configuration items

POST

/api/v1/cmdb/items

Create a CI

GET

/api/v1/cmdb/items/:id

Get CI with relationships

PATCH

/api/v1/cmdb/items/:id

Update CI attributes

POST

/api/v1/cmdb/items/:id/relationships

Add a relationship to another CI

GET

/api/v1/cmdb/topology

Get the full dependency graph as nodes/edges

Knowledge Base

GET

/api/v1/knowledge

List articles with search and category filter

POST

/api/v1/knowledge

Create a knowledge article

GET

/api/v1/knowledge/:id

Get full article content

PATCH

/api/v1/knowledge/:id

Update article content or metadata

POST

/api/v1/knowledge/search

Full-text semantic search across articles

bash

// Semantic search
POST /api/v1/knowledge/search
{
  "query": "how to reset VPN credentials for remote access",
  "limit": 5,
  "filters": { "category": "networking", "status": "published" }
}

Service Catalog

GET

/api/v1/catalog/items

List service catalog items (public)

POST

/api/v1/catalog/requests

Submit a service request

GET

/api/v1/catalog/requests/:id

Get request status and approvals

bash

POST /api/v1/catalog/requests
{
  "catalogItemId": "cat_laptop_request",
  "requestedBy": "usr_01HZ...",
  "fields": {
    "laptopModel": "MacBook Pro 16",
    "justification": "Current laptop failing, impacting productivity",
    "urgency": "high"
  }
}

Service catalog requests automatically create tickets, trigger approval workflows, and notify requesters of status changes. Wire up a workflow on the catalog.request_submitted event to customize the fulfillment flow.

CSAT Auto-Trigger

When a ticket created via the guest portal is resolved or closed, FlowOS automatically schedules a CSAT (Customer Satisfaction) survey email to the guest 30 minutes after resolution. Ratings are stored in csat_tokens and visible in the portal analytics dashboard.

•Survey email is sent 30 minutes after status = resolved | closed
•Star ratings 1–5 are captured via one-click email links
•Guests can add a text comment on the CSAT page
•Tokens expire after 30 days

GET

/api/portal/public/:slug/csat/:ref?rating=X&token=YYY

Record rating from email click (returns HTML confirmation page)

POST

/api/portal/public/:slug/csat/:ref

Submit rating + comment (body: { token, rating, comment })

Guest Ticket Email Threading

When an agent adds a public note (not a work note) on a ticket that has a guestEmail in its metadata, FlowOS sends a magic-link email to the guest. The link opens a thread view where the guest can see the conversation and reply without logging in.

•Magic link tokens are stored in portal_thread_tokens — one per email sent
•Tokens expire after 30 days
•Guest replies are added as public comments on the ticket
•The assigned agent is notified by email when a guest replies

GET

/api/portal/public/:slug/ticket/:ref/thread?token=ABC

Get ticket thread — full public conversation history

POST

/api/portal/public/:slug/ticket/:ref/comment?token=ABC

Add guest reply (body: { message })

Both CSAT and threading are non-fatal — if the email service is not configured or the slug cannot be resolved, the ticket action still completes and only the notification is skipped.