Integrations API - Support Bot

The Integrations API allows administrators to configure, manage, and synchronize data from external service management platforms. All endpoints require appropriate admin permissions.

Authentication

All integration endpoints require authentication and specific permissions:

integration.view - View integrations
integration.create - Create integrations
integration.edit - Update integrations
integration.delete - Delete integrations
integration.sync - Trigger manual synchronization

Authentication Types

Integrations support multiple authentication methods:

basic_auth - Username and password authentication
api_token - API token or key-based authentication
oauth2 - OAuth 2.0 authentication flow

Integration Object

string

required

Unique identifier for the integration (UUID)

service_name

string

required

Name of the external service (e.g., “ServiceNow”, “Jira”)

auth_type

string

required

Authentication type: basic_auth, api_token, or oauth2

config

object

required

Integration-specific configuration. Sensitive fields (passwords, tokens, secrets) are masked with ******** in API responses.ServiceNow Example:

{
  "url": "https://instance.service-now.com",
  "username": "admin",
  "password": "********",
  "lastSynced": "2026-03-01T10:30:00Z"
}

is_active

boolean

required

Whether the integration is currently active and enabled

last_synced_at

string

ISO 8601 timestamp of the last successful sync

last_sync_status

string

Status of the last sync attempt: success or error

last_sync_error

string

Error message from the last sync attempt (if failed)

updated_at

string

required

ISO 8601 timestamp of the last update

user_id

string

UUID of the user who created the integration

List All Integrations

Returns a list of all integrations in the system. Sensitive configuration fields are automatically masked in responses. Required Permission: integration.view

Response

success

boolean

required

Indicates if the request was successful

integrations

array

required

Array of integration objects

message

string

Error message (only present if success is false)

Example Request

curl -X GET https://api.example.com/integrations/all \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "integrations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "service_name": "ServiceNow",
      "auth_type": "basic_auth",
      "config": {
        "url": "https://dev12345.service-now.com",
        "username": "admin",
        "password": "********",
        "lastSynced": "2026-03-01T10:30:00Z"
      },
      "is_active": true,
      "last_synced_at": "2026-03-01T10:30:00Z",
      "last_sync_status": "success",
      "last_sync_error": null,
      "updated_at": "2026-03-01T10:30:00Z",
      "user_id": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}

Get Integration by ID

Fetches detailed information about a single integration. Required Permission: integration.view

Path Parameters

integration_id

string

required

The UUID of the integration to retrieve

Response

success

boolean

required

Indicates if the request was successful

integration

object

The integration object (only present if found)

message

string

Error or status message

Example Request

curl -X GET https://api.example.com/integrations/id/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "integration": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "service_name": "ServiceNow",
    "auth_type": "basic_auth",
    "config": {
      "url": "https://dev12345.service-now.com",
      "username": "admin",
      "password": "********"
    },
    "is_active": true,
    "last_synced_at": "2026-03-01T10:30:00Z",
    "last_sync_status": "success",
    "last_sync_error": null,
    "updated_at": "2026-03-01T10:30:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Error Response

{
  "success": false,
  "message": "Integration not found"
}

Create Integration

Creates a new integration configuration. The authenticated user will be associated with the integration. Required Permission: integration.create

Request Body

service_name

string

required

Name of the external service (e.g., “ServiceNow”, “Jira”, “GitHub”)

auth_type

string

required

Authentication method: basic_auth, api_token, or oauth2

config

object

required

Service-specific configuration object. Required fields vary by service.ServiceNow config:

url (string, required) - ServiceNow instance URL
username (string, required) - ServiceNow username
password (string, required) - ServiceNow password
lastSynced (string, optional) - Last sync timestamp

is_active

boolean

required

Set to true to enable the integration immediately

Response

success

boolean

required

Indicates if the creation was successful

integration

object

The created integration object (with sensitive fields masked)

message

string

Error message if creation failed

Example Request

curl -X POST https://api.example.com/integrations/create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "ServiceNow",
    "auth_type": "basic_auth",
    "config": {
      "url": "https://dev12345.service-now.com",
      "username": "admin",
      "password": "your_password"
    },
    "is_active": true
  }'

Example Response

{
  "success": true,
  "integration": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "service_name": "ServiceNow",
    "auth_type": "basic_auth",
    "config": {
      "url": "https://dev12345.service-now.com",
      "username": "admin",
      "password": "********"
    },
    "is_active": true,
    "last_synced_at": null,
    "last_sync_status": null,
    "last_sync_error": null,
    "updated_at": "2026-03-01T10:30:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Update Integration

Updates the configuration of an existing integration. All fields from the request body will replace the current values. Required Permission: integration.edit

Path Parameters

integration_id

string

required

The UUID of the integration to update

Request Body

service_name

string

required

Name of the external service

auth_type

string

required

Authentication method: basic_auth, api_token, or oauth2

config

object

required

Updated configuration object. This replaces the entire config.

is_active

boolean

required

Enable or disable the integration

Response

success

boolean

required

Indicates if the update was successful

integration

object

The updated integration object

message

string

Error or status message

Example Request

curl -X PUT https://api.example.com/integrations/update/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "ServiceNow Production",
    "auth_type": "basic_auth",
    "config": {
      "url": "https://prod.service-now.com",
      "username": "admin",
      "password": "new_password"
    },
    "is_active": true
  }'

Example Response

{
  "success": true,
  "integration": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "service_name": "ServiceNow Production",
    "auth_type": "basic_auth",
    "config": {
      "url": "https://prod.service-now.com",
      "username": "admin",
      "password": "********"
    },
    "is_active": true,
    "last_synced_at": "2026-03-01T10:30:00Z",
    "last_sync_status": "success",
    "last_sync_error": null,
    "updated_at": "2026-03-01T11:45:00Z",
    "user_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Delete Integration

Permanently removes an integration and its configuration. This action cannot be undone. Required Permission: integration.delete

Path Parameters

integration_id

string

required

The UUID of the integration to delete

Response

success

boolean

required

Indicates if the deletion was successful

message

string

required

Confirmation or error message

Example Request

curl -X DELETE https://api.example.com/integrations/delete/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "message": "Integration deleted successfully"
}

Error Response

{
  "success": false,
  "message": "Integration not found"
}

Trigger Manual Sync

Initiates a manual sync operation for a ServiceNow integration. This endpoint returns a Server-Sent Events (SSE) stream that provides real-time progress updates. Required Permission: integration.sync

Path Parameters

integration_id

string

required

The UUID of the integration to synchronize

Response

This endpoint returns a text/event-stream response with the following event types:

Event: progress

Emitted periodically during the sync operation.

batch

number

Current batch number being processed

totalBatches

number

Total number of batches to process

totalIncidents

number

Total number of incidents being synced

incidents

array

Array of incident IDs in the current batch

message

string

Human-readable progress message

Event: complete

Emitted when the sync operation completes successfully.

success

boolean

Always true for complete events

integration

object

Updated integration object with new sync timestamps

stats

object

Statistics about the sync operation:

added (number) - Number of new incidents added
total (number) - Total incidents processed
last_synced (string) - New last sync timestamp

Event: error

Emitted if the sync operation fails.

success

boolean

Always false for error events

message

string

Error description

Sync Workflow

Validation - Verifies integration exists and has required config (url, username, password)
Fetch - Retrieves new incidents from ServiceNow since last sync
Store - Saves raw incident data to local JSON file
Ingest - Processes incidents in batches (5 per batch) and stores in knowledge base
Version - Creates a versioned dataset for the sync operation
Update - Updates integration with sync status and timestamp

Example Request

curl -X POST https://api.example.com/integrations/sync/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

Example Response Stream

event: progress
data: {"batch":0,"totalBatches":0,"message":"Fetching incidents from ServiceNow..."}

event: progress
data: {"batch":0,"totalBatches":4,"totalIncidents":18,"message":"Ingesting 18 incidents in 4 batch(es)..."}

event: progress
data: {"batch":1,"totalBatches":4,"incidents":["INC001","INC002","INC003","INC004","INC005"],"totalIncidents":18,"message":"Batch 1 of 4 processed (5 incidents)"}

event: progress
data: {"batch":2,"totalBatches":4,"incidents":["INC006","INC007","INC008","INC009","INC010"],"totalIncidents":18,"message":"Batch 2 of 4 processed (5 incidents)"}

event: progress
data: {"batch":3,"totalBatches":4,"incidents":["INC011","INC012","INC013","INC014","INC015"],"totalIncidents":18,"message":"Batch 3 of 4 processed (5 incidents)"}

event: progress
data: {"batch":4,"totalBatches":4,"incidents":["INC016","INC017","INC018"],"totalIncidents":18,"message":"Batch 4 of 4 processed (3 incidents)"}

event: complete
data: {"success":true,"integration":{"id":"550e8400-e29b-41d4-a716-446655440000","service_name":"ServiceNow","auth_type":"basic_auth","config":{"url":"https://dev12345.service-now.com","username":"admin","password":"********","lastSynced":"2026-03-01T11:45:00Z"},"is_active":true,"last_synced_at":"2026-03-01T11:45:00Z","last_sync_status":"success","last_sync_error":null,"updated_at":"2026-03-01T11:45:00Z","user_id":"123e4567-e89b-12d3-a456-426614174000"},"stats":{"added":18,"total":18,"last_synced":"2026-03-01T11:45:00Z"}}

Error Cases

Integration Not Found:

event: error
data: {"success":false,"message":"Integration not found"}

Missing Configuration:

event: error
data: {"success":false,"message":"Missing ServiceNow configuration (url, username, password)"}

Sync Failed:

event: error
data: {"success":false,"message":"Failed to fetch incidents from ServiceNow: Connection timeout"}

Notes

The sync operation processes incidents in batches of 5 to provide granular progress updates
All synced incidents are stored in a versioned dataset for audit and rollback capabilities
The integration’s last_synced_at timestamp is only updated on successful completion
If no new incidents are found since the last sync, the operation completes without ingestion
Raw incident data is saved to src/data/incidentspulledfromsnow.json for debugging

Authentication

Chat

Knowledge Base

Feedback

Administration

​Authentication

​Authentication Types

​Integration Object

​List All Integrations

​Response

​Example Request

​Example Response

​Get Integration by ID

​Path Parameters

​Response

​Example Request

​Example Response

​Error Response

​Create Integration

​Request Body

​Response

​Example Request

​Example Response

​Update Integration

​Path Parameters

​Request Body

​Response

​Example Request

​Example Response

​Delete Integration

​Path Parameters

​Response

​Example Request

​Example Response

​Error Response

​Trigger Manual Sync

​Path Parameters

​Response

​Event: progress

​Event: complete

​Event: error

​Sync Workflow

​Example Request

​Example Response Stream

​Error Cases

​Notes

Build docs developers (and LLMs) love

Authentication

Authentication Types

Integration Object

List All Integrations

Response

Example Request

Example Response

Get Integration by ID

Path Parameters

Response

Example Request

Example Response

Error Response

Create Integration

Request Body

Response

Example Request

Example Response

Update Integration

Path Parameters

Request Body

Response

Example Request

Example Response

Delete Integration

Path Parameters

Response

Example Request

Example Response

Error Response

Trigger Manual Sync

Path Parameters

Response

Event: progress

Event: complete

Event: error

Sync Workflow

Example Request

Example Response Stream

Error Cases

Notes