Integrations API Reference

This guide provides detailed information about the Integrations API endpoints.

Authentication

All integration endpoints require authentication using a Project API Token. Include your token in the Authorization header:

bash

Authorization: Bearer YOUR_PROJECT_API_TOKEN

For more information about authentication, see the Authentication Guide.

List Integrations

Retrieve a list of all integrations for your project.

http

GET /api/v1/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

[
  {
    "uuid": "INT123",
    "type": "Integrations::WebhookIntegration",
    "name": "Slack Webhook",
    "settings": {
      "webhook_url": "https://hooks.slack.com/services/..."
    },
    "editable": true,
    "deletable": true,
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
]

Create Integration

Create a new integration for your project. The process varies depending on the integration type.

Integration Types

The following integration types are supported:

Webhook - Send HTTP POST requests to a custom webhook URL
Email - Send email notifications to a specified email address
SSH Server Restart - Automatically restart servers via SSH when incidents occur
SMS - Send SMS notifications (requires paid plan and phone verification)
Slack - Send notifications to Slack channels (requires OAuth setup)

Webhook Integration

Send HTTP POST requests to a custom webhook URL when incidents occur.

Create Webhook Integration

http

POST /api/v1/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": {
      "type": "Integrations::WebhookIntegration",
      "settings": {
        "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
      }
    }
  }'

Request Body

Parameter	Type	Description	Required
integration	object	Integration object	Yes
integration.type	string	Must be `Integrations::WebhookIntegration`	Yes
integration.settings	object	Integration settings	Yes
integration.settings.webhook_url	string	The webhook URL to send POST requests to	Yes

Webhook Payload

When an incident occurs, the webhook will receive a POST request with the following JSON payload:

json

{
  "resource_name": "https://example.com",
  "resource_url": "https://example.com",
  "resource_type": "NetworkMonitor",
  "incident_type": "timeout",
  "incident_status": "ongoing",
  "incident_duration": null,
  "incident_message": "Request timeout after 30 seconds"
}

Response

json

{
  "uuid": "INT123",
  "type": "Integrations::WebhookIntegration",
  "name": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL",
  "settings": {
    "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  },
  "editable": true,
  "deletable": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Email Integration

Send email notifications to a specified email address when incidents occur.

Create Email Integration

http

POST /api/v1/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": {
      "type": "Integrations::EmailIntegration",
      "settings": {
        "email": "alerts@example.com"
      }
    }
  }'

Request Body

Parameter	Type	Description	Required
integration	object	Integration object	Yes
integration.type	string	Must be `Integrations::EmailIntegration`	Yes
integration.settings	object	Integration settings	Yes
integration.settings.email	string	The email address to send notifications to (must be valid email format)	Yes

Response

json

{
  "uuid": "INT123",
  "type": "Integrations::EmailIntegration",
  "name": "alerts@example.com",
  "settings": {
    "email": "alerts@example.com"
  },
  "editable": true,
  "deletable": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Note: If the email belongs to a user account, that user must have verified their email address before notifications can be sent.

SSH Server Restart Integration

Automatically restart servers via SSH when incidents occur. This integration requires SSH access credentials.

Create SSH Server Restart Integration

http

POST /api/v1/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": {
      "type": "Integrations::SshServerRestartIntegration",
      "settings": {
        "ip": "192.168.1.100",
        "username": "admin",
        "password": "secure_password",
        "port": 22
      }
    }
  }'

Request Body

Parameter	Type	Description	Required
integration	object	Integration object	Yes
integration.type	string	Must be `Integrations::SshServerRestartIntegration`	Yes
integration.settings	object	Integration settings	Yes
integration.settings.ip	string	The IP address or hostname of the server	Yes
integration.settings.username	string	SSH username	Yes
integration.settings.password	string	SSH password	Yes
integration.settings.port	integer	SSH port (default: 22)	Yes

Response

json

{
  "uuid": "INT123",
  "type": "Integrations::SshServerRestartIntegration",
  "name": "192.168.1.100 (admin)",
  "settings": {
    "ip": "192.168.1.100",
    "username": "admin",
    "password": "secure_password",
    "port": 22
  },
  "editable": true,
  "deletable": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Security Note: The password is stored securely in the database. When an incident occurs, the integration will execute sudo reboot on the target server.

SMS Integration

Send SMS notifications to a phone number when incidents occur. This integration requires a paid plan and phone number verification.

Step 1: Send Verification Code

Before creating an SMS integration, you must verify the phone number by sending a verification code.

http

POST /api/v1/integrations/sms/send_verification_code
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations/sms/send_verification_code \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890"
  }'

Request Body

Parameter	Type	Description	Required
phone_number	string	Phone number in E.164 format (e.g., +1234567890)	Yes

Response

json

{
  "success": true,
  "message": "Verification code sent successfully"
}

Error Responses:

If the project doesn't have a paid plan:

json

{
  "success": false,
  "error": "paid_plan_required",
  "message": "SMS integrations require a paid plan"
}

If phone number is missing:

json

{
  "success": false,
  "error": "phone_number_required",
  "message": "Phone number is required"
}

Step 2: Create SMS Integration

After receiving the verification code via SMS, create the integration with the verification code.

http

POST /api/v1/integrations
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": {
      "type": "Integrations::SmsIntegration",
      "settings": {
        "phone_number": "+1234567890",
        "verification_code": "123456"
      }
    }
  }'

Request Body

Parameter	Type	Description	Required
integration	object	Integration object	Yes
integration.type	string	Must be `Integrations::SmsIntegration`	Yes
integration.settings	object	Integration settings	Yes
integration.settings.phone_number	string	The phone number to send SMS to (must match the verified number)	Yes
integration.settings.verification_code	string	The verification code received via SMS	Yes (in production)

Response

json

{
  "uuid": "INT123",
  "type": "Integrations::SmsIntegration",
  "name": "SMS +1234567890",
  "settings": {
    "phone_number": "+1234567890"
  },
  "editable": true,
  "deletable": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Note: In non-production environments, the verification code check is skipped for testing purposes.

Slack Integration

Send notifications to Slack channels when incidents occur. This integration requires OAuth setup through Slack.

Step 1: Initiate Slack OAuth

Start the Slack OAuth setup process by requesting an OAuth URL.

http

POST /api/v1/integrations/slack/initiate
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/integrations/slack/initiate \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "oauth_url": "https://slack.com/oauth/v2/authorize?client_id=...&redirect_uri=...&state=...",
  "state": "abc123def456...",
  "redirect_uri": "https://app.uptinio.com/auth/slack/callback?project_uuid=PROJECT_UUID"
}

Step 2: Complete OAuth Flow

Redirect the user to the OAuth URL returned in the response. The user will be taken to Slack to authorize the application.
Slack will redirect back to the callback URL with an authorization code.
The integration is automatically created after successful authorization. The callback endpoint handles the OAuth token exchange and creates the integration.

Note: The OAuth callback must be completed in a web browser. After authorization, the user will be redirected to the integrations page. The integration will be available via the API immediately after creation.

Integration Details

Once created, the Slack integration will:

Send incident notifications to the selected Slack channel
Include interactive buttons to resolve incidents directly from Slack
Update incident messages when incidents are resolved

The integration settings include:

bot_token - Bot token for posting messages
user_token - User token for managing channels
channel_id - ID of the Slack channel
webhook_url - Webhook URL for posting messages
bot_user_id - ID of the bot user

These settings are automatically configured during OAuth and are encrypted in the database.

Response (After OAuth Completion)

json

{
  "uuid": "INT123",
  "type": "Integrations::SlackIntegration",
  "name": "My Workspace #alerts",
  "settings": {
    "bot_token": "xoxb-...",
    "user_token": "xoxp-...",
    "channel_id": "C1234567890",
    "webhook_url": "https://hooks.slack.com/services/...",
    "bot_user_id": "U1234567890"
  },
  "editable": false,
  "deletable": true,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Note: Slack integrations are not editable after creation. To change settings, delete and recreate the integration.

Delete Integration

Delete an integration.

http

DELETE /api/v1/integrations/:id
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X DELETE https://app.uptinio.com/api/v1/integrations/INT123 \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

Status: 204 No Content

If the integration cannot be deleted (e.g., it's a system integration), you'll receive:

Status: 422 Unprocessable Entity

json

{
  "error": "This integration cannot be deleted."
}

Attaching Integrations to Servers

To send server alerts (CPU, RAM, disk, downtime, etc.) to an integration, attach the integration to the server using the Servers API:

List integrations on a server: GET /api/v1/servers/:uuid/integrations
Attach an integration: POST /api/v1/servers/:uuid/integrations with body {"integration_id": "<INTEGRATION_UUID>"}
Detach an integration: DELETE /api/v1/servers/:uuid/integrations/:integration_id

Example: attach a webhook to a server

bash

# Create a webhook integration (if you haven't already)
curl -X POST https://app.uptinio.com/api/v1/integrations \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration": {
      "type": "Integrations::WebhookIntegration",
      "settings": { "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL" }
    }
  }'

# Attach that integration to server SRV123 (use the integration uuid from the create response)
curl -X POST "https://api.uptinio.com/api/v1/servers/SRV123/integrations" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"integration_id": "INT456"}'

See Server Integrations in the Servers API reference for full request/response details.

Error Codes

Code	Description
integration_not_found	The specified integration does not exist
invalid_request	The request parameters are invalid
unauthorized	Invalid or missing authentication token
unprocessable_entity	The integration cannot be deleted

Integrations API Reference ​

Authentication ​

List Integrations ​

Response ​

Create Integration ​

Integration Types ​

Webhook Integration ​

Create Webhook Integration ​

Request Body ​

Webhook Payload ​

Response ​

Email Integration ​

Create Email Integration ​

Request Body ​

Response ​

SSH Server Restart Integration ​

Create SSH Server Restart Integration ​

Request Body ​

Response ​

SMS Integration ​

Step 1: Send Verification Code ​

Request Body ​

Response ​

Step 2: Create SMS Integration ​

Request Body ​

Response ​

Slack Integration ​

Step 1: Initiate Slack OAuth ​

Response ​

Step 2: Complete OAuth Flow ​

Integration Details ​

Response (After OAuth Completion) ​

Delete Integration ​

Response ​

Attaching Integrations to Servers ​

Error Codes ​

Next Steps ​

Integrations API Reference

Authentication

List Integrations

Response

Create Integration

Integration Types

Webhook Integration

Create Webhook Integration

Request Body

Webhook Payload

Response

Email Integration

Create Email Integration

Request Body

Response

SSH Server Restart Integration

Create SSH Server Restart Integration

Request Body

Response

SMS Integration

Step 1: Send Verification Code

Request Body

Response

Step 2: Create SMS Integration

Request Body

Response

Slack Integration

Step 1: Initiate Slack OAuth

Response

Step 2: Complete OAuth Flow

Integration Details

Response (After OAuth Completion)

Delete Integration

Response

Attaching Integrations to Servers

Error Codes

Next Steps