Send Alerts

This page provides the complete API reference for sending alerts to OpsFusion. Use these endpoints to create alerts that will notify your on-call teams.

---

Quick Start (TL;DR)

For developers who want to send an alert right now:

# Replace YOUR_ACCOUNT_ID, YOUR_API_KEY, and YOUR_TEAM_ID with your actual values
curl -X POST 'https://api.opsfusion.cloud/v1/account/YOUR_ACCOUNT_ID/push/alert' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "teamId": YOUR_TEAM_ID,
    "title": "Test Alert",
    "description": "Testing OpsFusion API integration",
    "severity": 3,
    "status": 1,
    "labels": {
      "environment": "dev",
      "service": "opsfusion-quickstart"
    }
  }'

You can also send a JSON array of alert objects to submit several at once — see Batch Alerts below.

Get these values:

• YOUR_API_KEY - Create one if you haven’t
• YOUR_ACCOUNT_ID - Find your Account ID
• YOUR_TEAM_ID - Find your Team ID — must be an integer, not a string

Expect: 200 OK response and the on-call person receives a notification.

Troubleshooting:

• If you received 200 OK but don’t see the alert in your team’s alerts, check the Default team - the alert may have been sent to an invalid team ID. See The “Default” Team for more information.

Code Examples

Python

import requests

url = "https://api.opsfusion.cloud/v1/account/YOUR_ACCOUNT_ID/push/alert"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "teamId": YOUR_TEAM_ID,
    "title": "Service Degradation Detected",
    "description": "Response time increased to 2.5s (threshold: 1s)",
    "severity": 2,
    "status": 1,
    "labels": {
        "service": "checkout-api",
        "environment": "production"
    }
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    print("Alert sent successfully")
else:
    print(f"Error: {response.status_code} - {response.text}")

Node.js

const axios = require('axios');

const sendAlert = async () => {
  try {
    const response = await axios.post(
      'https://api.opsfusion.cloud/v1/account/YOUR_ACCOUNT_ID/push/alert',
      {
        teamId: YOUR_TEAM_ID,
        title: 'Service Degradation Detected',
        description: 'Response time increased to 2.5s (threshold: 1s)',
        severity: 2,
        status: 1,
        labels: {
          service: 'checkout-api',
          environment: 'production'
        }
      },
      {
        headers: {
          'Authorization': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Alert sent successfully');
  } catch (error) {
    console.error('Error sending alert:', error.response?.data || error.message);
  }
};

sendAlert();

Go

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
)

type Alert struct {
  TeamID      int64             `json:"teamId"`
  Title       string            `json:"title"`
  Description string            `json:"description"`
  Severity    int               `json:"severity"`
  Status      int               `json:"status"`
  Labels      map[string]string `json:"labels"`
}

func sendAlert() error {
  url := "https://api.opsfusion.cloud/v1/account/YOUR_ACCOUNT_ID/push/alert"
  apiKey := "YOUR_API_KEY"

  alert := Alert{
    TeamID:      YOUR_TEAM_ID,
    Title:       "Service Degradation Detected",
    Description: "Response time increased to 2.5s (threshold: 1s)",
    Severity:    2,
    Status:      1,
    Labels: map[string]string{
      "service":     "checkout-api",
      "environment": "production",
    },
  }

  jsonData, err := json.Marshal(alert)
  if err != nil {
    return fmt.Errorf("error marshaling JSON: %w", err)
  }

  req, err := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
  if err != nil {
    return fmt.Errorf("error creating request: %w", err)
  }

  req.Header.Set("Authorization", apiKey)
  req.Header.Set("Content-Type", "application/json")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    return fmt.Errorf("error sending request: %w", err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)

  if resp.StatusCode == http.StatusOK {
    fmt.Println("Alert sent successfully")
    return nil
  }

  return fmt.Errorf("error: %d - %s", resp.StatusCode, string(body))
}

func main() {
  if err := sendAlert(); err != nil {
    fmt.Printf("Failed to send alert: %v\n", err)
  }
}

Batch Alerts

The endpoint also accepts a JSON array of alert objects, so you can send multiple alerts in a single request (up to 25 alerts):

alerts = [
    {
        "teamId": YOUR_TEAM_ID,
        "title": "Alert 1",
        "description": "Description 1",
        "severity": 2,
        "status": 1
    },
    {
        "teamId": YOUR_TEAM_ID,
        "title": "Alert 2",
        "description": "Description 2",
        "severity": 1,
        "status": 1
    }
]

response = requests.post(url, headers=headers, json=alerts)

Error Handling

import time

def send_alert_with_retry(payload, max_retries=3):
    """Send alert with exponential backoff retry logic"""
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=payload)

            if response.status_code == 200:
                return response
            elif response.status_code == 429:
                # Rate limited - exponential backoff
                wait_time = 2 ** attempt
                print(f"Rate limited. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            elif response.status_code >= 500:
                # Server error - exponential backoff
                wait_time = 2 ** attempt
                print(f"Server error. Retrying in {wait_time}s...")
                time.sleep(wait_time)
            else:
                # Client error - don't retry
                print(f"Client error: {response.status_code} - {response.text}")
                return response
        except requests.exceptions.RequestException as e:
            print(f"Request failed: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

---

Request Details

Send alerts in OpsFusion’s native format. If you’re integrating a specific monitoring tool instead, see the Integrations section for setup guides covering Prometheus Alertmanager and other supported tools.

Request URL

https://api.opsfusion.cloud/v1/account/{accountId}/push/alert

Replace {accountId} with your OpsFusion account ID.

Authentication

All requests must include authentication in the Authorization header.

Authorization: YOUR_API_KEY

See Create an API Key for instructions on generating API keys.

Path Parameters

Parameter	Required	Description
accountId	Yes	Your OpsFusion account ID

Request Headers

Header	Required	Value
Authorization	Yes	YOUR_API_KEY
Content-Type	Yes	application/json

Request Body

The request body accepts either a single JSON alert object, or a JSON array containing 1-25 alert objects.

Alert Object Fields

Field	Type	Required	Description	Constraints
teamId	integer	Yes	Team ID	13-digit integer
title	string	Yes	Brief alert title	1-200 characters
description	string	Yes	Detailed description of the issue	1-2048 characters
severity	integer	Yes	Alert severity level	1 (critical), 2 (high), or 3 (medium/low)
status	integer	Yes	Alert status	1 (firing) or 3 (resolved)
labels	object	No	Custom key-value pairs for categorization	Max 50 labels, key 1-64 characters, value 1-128 characters

Constraints

• Array size: if sending an array, 1-25 alerts per request
• Title: Automatically truncated to 200 characters
• Description: Automatically truncated to 2048 characters
• Status: Status 1 will open an alert while 3 will resolve it
• Labels: Max 50 key-value pairs, each key 1-64 characters, and each value 1-128 characters

---

Response Codes

This endpoint returns the following HTTP status codes:

Status Code	Description
200 OK	Alert(s) successfully processed
400 Bad Request	Invalid request format or missing required fields
403 Forbidden	Authentication failed or insufficient permissions
404 Not Found	Account ID not found
429 Too Many Requests	Rate limit exceeded; retry after delay
500 Internal Server Error	Server error; retry with exponential backoff

Response Body

Success Response (200 OK)

{}

Returns an empty object on success.

Error Response (4xx/5xx)

{
  "message": "Error description"
}

Severity Levels

Severity	Value	When to Use
Critical	1	Service down, data loss, security breach
High	2	Degraded performance, approaching limits
Medium/Low	3	Warning conditions, informational

Alert Status

Status	Value	Description
Firing	1	Alert is active and requires attention
Resolved	3	Issue has been resolved

Status 2 is reserved for acknowledged alerts and can’t be set via API

Rate Limits

API requests are rate limited to ensure service stability. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Best Practice: Implement exponential backoff when receiving 429 responses.

The “Default” Team

Built-in Fallback Team

Every OpsFusion account includes a special “Default” team that automatically catches alerts sent to invalid or non-existent team IDs. This ensures no alerts are lost due to misconfiguration.

How it works:

• If you send an alert with an invalid or non-existent teamId, the alert will be automatically assigned to the Default team
• The Default team catches misrouted alerts, helping you identify configuration issues
• You can configure the Default team like any other team with on-call schedules and notifications

Use cases:

• Fallback safety net - Ensure alerts are never lost due to incorrect team IDs
• Testing and development - Use the Default team to test alert delivery without affecting production teams
• Alert monitoring - Watch the Default team for misconfigured integrations or invalid team references

Troubleshooting

400 Bad Request

• Verify JSON is properly formatted
• Check that all required fields are present
• Ensure field values meet constraints (e.g., teamId is 13 digits)
• Verify severity and status use correct integer values

403 Forbidden

• Check that your API key is valid and not expired
• Verify you’re using the correct Authorization header format
• Ensure your API key has permission for the specified account/team

404 Not Found

• Verify the account ID in the URL path is correct
• Check that the team ID exists in your OpsFusion account

429 Too Many Requests

• Implement exponential backoff retry logic
• Reduce request frequency
• Consider batching multiple alerts in single requests

Support

For API support:

• Email: support@opsfusion.cloud
• See API Overview for getting started guide