SDK & Client Libraries
The recommended way to interact with the ITSM API is by using one of our official SDKs. We maintain first-party libraries for JavaScript/TypeScript, Python, and Go that handle authentication, retries, pagination, and webhook verification out of the box.
Official libraries
PHP
A popular general-purpose scripting language that is especially suited to web development.
Ruby
A dynamic, open source programming language with a focus on simplicity and productivity.
Python
Python is a programming language that lets you work quickly and integrate systems more effectively.
JavaScript / TypeScript
The official JavaScript SDK ships with full TypeScript definitions, tree-shakeable ESM builds, and works in Node.js 18+ and modern browsers. Install it from npm:
Installation
npm install @itsm/api-client
Or with other package managers:
pnpm add @itsm/api-client
yarn add @itsm/api-client
Quick start
import { ItsmClient } from '@itsm/api-client'
const client = new ItsmClient({
baseUrl: 'https://api.your-domain.com',
token: process.env.ITSM_API_TOKEN,
})
// Create a ticket with AI triage
const ticket = await client.tickets.create({
title: 'VPN disconnects every 15 minutes',
description: 'GlobalProtect 6.1 on Windows 11...',
type: 'incident',
source: 'api',
})
console.log(ticket.ticket_number) // INC-00042
console.log(ticket.ai_confidence) // 0.94
Python
The Python SDK supports Python 3.9+ and provides both synchronous and async clients. Install it from PyPI:
Installation
pip install itsm-api-python
The async client uses httpx under the hood and works with asyncio and trio:
pip install itsm-api-python[async]
Quick start
from itsm_api import ItsmClient
client = ItsmClient(
base_url="https://api.your-domain.com",
token="your-api-token",
)
# Create a ticket with AI triage
ticket = client.tickets.create(
title="VPN disconnects every 15 minutes",
description="GlobalProtect 6.1 on Windows 11...",
type="incident",
source="api",
)
print(ticket.ticket_number) # INC-00042
print(ticket.ai_confidence) # 0.94
Go
The Go SDK requires Go 1.21+ and follows idiomatic Go patterns with context propagation and structured errors. Install it with go get:
Installation
go get github.com/itsm-automation/itsm-api-go
Quick start
package main
import (
"context"
"fmt"
"log"
itsm "github.com/itsm-automation/itsm-api-go"
)
func main() {
client := itsm.NewClient(
itsm.WithBaseURL("https://api.your-domain.com"),
itsm.WithToken("your-api-token"),
)
ticket, err := client.Tickets.Create(context.Background(), &itsm.CreateTicketParams{
Title: "VPN disconnects every 15 minutes",
Description: "GlobalProtect 6.1 on Windows 11...",
Type: itsm.TicketTypeIncident,
Source: itsm.SourceAPI,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(ticket.TicketNumber) // INC-00042
fmt.Println(ticket.AIConfidence) // 0.94
}
SDK features
All official SDKs share a consistent set of features designed for production use:
Automatic retry with backoff
Failed requests due to network errors or 5xx responses are automatically retried up to 3 times with exponential backoff. You can configure the retry count and maximum delay.
Retry configuration
const client = new ItsmClient({
token: process.env.ITSM_API_TOKEN,
maxRetries: 5,
retryDelay: 1000, // initial delay in ms
})
Rate limit handling
When the API returns a 429 Too Many Requests response, the SDK reads the Retry-After header and automatically waits before retrying. No manual handling is needed.
Pagination helpers
All list endpoints return paginated results. The SDKs provide iteration helpers so you never need to manage cursors manually.
Pagination
// Automatically fetches all pages
for await (const ticket of client.tickets.listAutoPaginate({
status: 'open',
})) {
console.log(ticket.ticket_number)
}
TypeScript types
The JavaScript SDK exports full TypeScript types for every request and response model. Autocompletion and compile-time validation are available for all endpoints.
import type {
Ticket,
CreateTicketParams,
ListTicketsParams,
TriageResult,
Attachment,
Workflow,
} from '@itsm/api-client'
Webhook verification
All SDKs include helpers for verifying HMAC-SHA256 webhook signatures. Always verify the signature before processing webhook payloads to ensure authenticity.
The verification function takes the raw request body, the X-ITSM-Signature header, and your webhook secret. It returns true if the signature is valid or throws an error if verification fails.
Webhook verification
import { verifyWebhookSignature } from '@itsm/api-client'
app.post('/webhooks/itsm', (req, res) => {
const isValid = verifyWebhookSignature({
payload: req.body,
signature: req.headers['x-itsm-signature'],
secret: process.env.WEBHOOK_SECRET,
})
if (!isValid) {
return res.status(401).send('Invalid signature')
}
// Process the webhook event
const event = JSON.parse(req.body)
console.log(event.type) // e.g. "ticket.created"
})
Community SDKs
In addition to our official SDKs, the community maintains libraries for additional languages. These are not officially supported but are listed here for convenience.
- Name
Ruby- Type
- gem install itsm-api-ruby
- Description
Maintained by the community. Covers tickets, triage, and webhook verification. GitHub
- Name
Java- Type
- Maven: com.itsm/api-client
- Description
Community-maintained Java SDK with support for Spring Boot integration. GitHub
- Name
PHP- Type
- composer require itsm/api-client
- Description
Community-maintained PHP SDK compatible with Laravel and Symfony. GitHub
Community SDKs are maintained by third-party contributors and may not cover all API endpoints. If you encounter issues, please file them on the respective GitHub repositories. We welcome contributions to make these libraries more complete.