Tickets

Tickets are the central resource of the ITSM platform — every incident, service request, problem, change, and task flows through the ticket lifecycle. On this page, we'll dive into the different ticket endpoints you can use to create, triage, update, and resolve tickets programmatically. AI-powered classification enriches each ticket with category, intent, and sentiment automatically at creation time.

The ticket model

The ticket model contains all the information about an ITSM ticket, including its classification, assignment, SLA deadlines, and AI-enriched metadata. Every ticket belongs to an organization (tenant) and follows a defined lifecycle from new through closed or cancelled.

Properties

Name
id
Type
string
Description
Unique identifier for the ticket (UUID).
Name
ticket_number
Type
string
Description
Human-readable ticket number, unique per organization (e.g., INC-00042).
Name
organization_id
Type
string
Description
The tenant ID that owns this ticket.
Name
title
Type
string
Description
Short summary of the ticket.
Name
description
Type
string
Description
Detailed description of the issue or request.
Name
type
Type
string
Description
The ticket type. One of incident, service_request, problem, change, or task.
Name
status
Type
string
Description
Current lifecycle status. One of new, open, in_progress, pending, on_hold, resolved, closed, or cancelled.
Name
priority
Type
string
Description
Priority level. One of critical, high, medium, or low.
Name
source
Type
string
Description
Channel the ticket originated from. One of portal, email, phone, chat, api, monitoring, or walk_in.
Name
requester_id
Type
string
Description
The ID of the user who created the ticket.
Name
assignee_id
Type
string
Description
The ID of the agent assigned to the ticket.
Name
team_id
Type
string
Description
The ID of the team assigned to the ticket.
Name
category
Type
string
Description
Category auto-classified by AI at triage time.
Name
subcategory
Type
string
Description
Subcategory auto-classified by AI at triage time.
Name
sla_response_due_at
Type
timestamp
Description
SLA deadline for first response.
Name
sla_resolution_due_at
Type
timestamp
Description
SLA deadline for resolution.
Name
ai_confidence
Type
number
Description
AI classification confidence score between 0 and 1.
Name
ai_intent
Type
string
Description
Intent detected by the AI model during triage.
Name
sentiment
Type
string
Description
Requester sentiment detected by AI. One of positive, neutral, negative, or frustrated.
Name
created_at
Type
timestamp
Description
Timestamp of when the ticket was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the ticket was last updated.
Name
resolved_at
Type
timestamp
Description
Timestamp of when the ticket was resolved.
Name
closed_at
Type
timestamp
Description
Timestamp of when the ticket was closed.

GET/v1/tickets

List all tickets

This endpoint allows you to retrieve a paginated list of all tickets in your organization. By default, a maximum of ten tickets are shown per page. You can filter by status, priority, type, and assignee.

Optional attributes

Name
status
Type
string
Description
Filter tickets by status (e.g., open, in_progress, resolved).
Name
priority
Type
string
Description
Filter tickets by priority (e.g., critical, high).
Name
type
Type
string
Description
Filter tickets by type (e.g., incident, service_request).
Name
assignee_id
Type
string
Description
Filter tickets by assigned agent ID.
Name
page
Type
integer
Description
The page number for pagination.
Name
limit
Type
integer
Description
Limit the number of tickets returned per page.

Request

GET

/v1/tickets

curl -G http://localhost:3000/v1/tickets \
  -H "Authorization: Bearer {token}" \
  -d status=open \
  -d priority=high \
  -d limit=10

Response

{
  "has_more": true,
  "page": 1,
  "limit": 10,
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "ticket_number": "INC-00042",
      "organization_id": "org_9f8e7d6c5b4a",
      "title": "VPN connection drops every 15 minutes",
      "description": "Since this morning, my VPN disconnects approximately every 15 minutes. I have tried restarting the client and my laptop. Running GlobalProtect 6.1 on Windows 11.",
      "type": "incident",
      "status": "open",
      "priority": "high",
      "source": "portal",
      "requester_id": "usr_a1b2c3d4e5f6",
      "assignee_id": "usr_f6e5d4c3b2a1",
      "team_id": "team_network_ops",
      "category": "Network",
      "subcategory": "VPN",
      "sla_response_due_at": 1708786800,
      "sla_resolution_due_at": 1708873200,
      "ai_confidence": 0.94,
      "ai_intent": "connectivity_issue",
      "sentiment": "frustrated",
      "created_at": 1708783200,
      "updated_at": 1708784100,
      "resolved_at": null,
      "closed_at": null
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
      // ...
    }
  ]
}

POST/v1/tickets

Create a ticket

This endpoint allows you to create a new ticket. You must provide a title and description at minimum. The system will auto-assign a ticket_number, run AI triage to populate category, subcategory, ai_confidence, ai_intent, and sentiment, and calculate SLA deadlines based on the resolved priority.

Required attributes

Name
title
Type
string
Description
Short summary of the issue or request.
Name
description
Type
string
Description
Detailed description of the issue or request.

Optional attributes

Name
type
Type
string
Description
Ticket type. Defaults to incident if not provided. One of incident, service_request, problem, change, or task.
Name
priority
Type
string
Description
Priority level. If omitted, AI triage will determine priority automatically. One of critical, high, medium, or low.
Name
source
Type
string
Description
Originating channel. Defaults to api. One of portal, email, phone, chat, api, monitoring, or walk_in.

Request

POST

/v1/tickets

curl http://localhost:3000/v1/tickets \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cannot access shared drive after password reset",
    "description": "After resetting my Active Directory password this morning, I can no longer access the shared file server. Getting Access Denied errors. Other network resources work fine.",
    "type": "incident",
    "source": "portal"
  }'

Response

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "ticket_number": "INC-00127",
  "organization_id": "org_9f8e7d6c5b4a",
  "title": "Cannot access shared drive after password reset",
  "description": "After resetting my Active Directory password this morning, I can no longer access the shared file server. Getting Access Denied errors. Other network resources work fine.",
  "type": "incident",
  "status": "new",
  "priority": "medium",
  "source": "portal",
  "requester_id": "usr_a1b2c3d4e5f6",
  "assignee_id": null,
  "team_id": null,
  "category": "Access Management",
  "subcategory": "File Share Permissions",
  "sla_response_due_at": 1708801200,
  "sla_resolution_due_at": 1708970400,
  "ai_confidence": 0.91,
  "ai_intent": "access_restoration",
  "sentiment": "neutral",
  "created_at": 1708790400,
  "updated_at": 1708790400,
  "resolved_at": null,
  "closed_at": null
}

GET/v1/tickets/:id

Retrieve a ticket

This endpoint allows you to retrieve a ticket by providing its UUID. Refer to the list at the top of this page to see which properties are included with ticket objects.

Request

GET

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ticket_number": "INC-00042",
  "organization_id": "org_9f8e7d6c5b4a",
  "title": "VPN connection drops every 15 minutes",
  "description": "Since this morning, my VPN disconnects approximately every 15 minutes. I have tried restarting the client and my laptop. Running GlobalProtect 6.1 on Windows 11.",
  "type": "incident",
  "status": "open",
  "priority": "high",
  "source": "portal",
  "requester_id": "usr_a1b2c3d4e5f6",
  "assignee_id": "usr_f6e5d4c3b2a1",
  "team_id": "team_network_ops",
  "category": "Network",
  "subcategory": "VPN",
  "sla_response_due_at": 1708786800,
  "sla_resolution_due_at": 1708873200,
  "ai_confidence": 0.94,
  "ai_intent": "connectivity_issue",
  "sentiment": "frustrated",
  "created_at": 1708783200,
  "updated_at": 1708784100,
  "resolved_at": null,
  "closed_at": null
}

PATCH/v1/tickets/:id

Update a ticket

This endpoint allows you to perform a partial update on a ticket. You can update assignment, status, priority, and other mutable fields. Transitioning status to resolved will automatically set resolved_at, and transitioning to closed will set closed_at.

Optional attributes

Name
status
Type
string
Description
Update the ticket lifecycle status.
Name
priority
Type
string
Description
Update the ticket priority level.
Name
assignee_id
Type
string
Description
Reassign the ticket to a different agent.
Name
team_id
Type
string
Description
Reassign the ticket to a different team.
Name
title
Type
string
Description
Update the ticket summary.
Name
description
Type
string
Description
Update the ticket description.

Request

PATCH

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X PATCH http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "assignee_id": "usr_f6e5d4c3b2a1",
    "team_id": "team_network_ops"
  }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ticket_number": "INC-00042",
  "organization_id": "org_9f8e7d6c5b4a",
  "title": "VPN connection drops every 15 minutes",
  "description": "Since this morning, my VPN disconnects approximately every 15 minutes. I have tried restarting the client and my laptop. Running GlobalProtect 6.1 on Windows 11.",
  "type": "incident",
  "status": "in_progress",
  "priority": "high",
  "source": "portal",
  "requester_id": "usr_a1b2c3d4e5f6",
  "assignee_id": "usr_f6e5d4c3b2a1",
  "team_id": "team_network_ops",
  "category": "Network",
  "subcategory": "VPN",
  "sla_response_due_at": 1708786800,
  "sla_resolution_due_at": 1708873200,
  "ai_confidence": 0.94,
  "ai_intent": "connectivity_issue",
  "sentiment": "frustrated",
  "created_at": 1708783200,
  "updated_at": 1708790500,
  "resolved_at": null,
  "closed_at": null
}

DELETE/v1/tickets/:id

Delete a ticket

This endpoint allows you to delete a ticket. Note: deleting a ticket is a permanent action and will remove all associated audit history, comments, and attachments. In most ITSM workflows, you should transition tickets to cancelled or closed status instead of deleting them.

Request

DELETE

/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890

curl -X DELETE http://localhost:3000/v1/tickets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"