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. To list, acknowledge, or close alerts, see the Alerts reference.

---

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. It needs the Alert Push or Admin role.
• 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 - alerts for an unknown team ID are accepted and routed there. 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:
                # Quota reached - back off before retrying
                wait_time = 2 ** attempt
                print(f"Quota reached. 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

You can send alerts in OpsFusion’s native format or in the Prometheus Alertmanager format. If you’re integrating a specific monitoring tool instead, see the Integrations section for setup guides.

Endpoints

Endpoint	Format
POST /account/{accountId}/push/alert	OpsFusion standard format (documented below)
POST /account/{accountId}/push/alertmanager	Prometheus Alertmanager webhook format (see Alertmanager Endpoint)

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. Both formats are accepted:

Authorization: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

The key needs the Alert Push or Admin role. A Read Only key can’t push alerts. See Authentication and Roles and Create an API Key.

Path Parameters

Parameter	Required	Description
accountId	Yes	Your OpsFusion account ID

Request Headers

Header	Required	Value
Authorization	Yes	YOUR_API_KEY or Bearer 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	Valid team ID
title	string	Yes	Brief alert title	1-200 characters; longer titles are truncated
description	string	Yes	Detailed description of the issue	1-2048 characters; longer descriptions are truncated
severity	integer	Yes	Alert severity level	1 (critical), 2 (warning), or 3 (info)
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. Keys and values may contain any characters, including quotes.
• Unknown fields: Fields not listed above are rejected with 400.

Duplicate Alerts

OpsFusion groups alerts that share the same account, team, title, and labels.

• Firing (status 1): If an open or acknowledged alert with the same title and labels exists from recently, OpsFusion increments its count and adds a duplicate entry to its timeline instead of creating a new alert. Otherwise it creates a new alert.
• Resolved (status 3): OpsFusion closes every matching alert that isn’t closed yet. If there are none, it creates a closed alert.

Duplicates still count toward your quotas. Alerts with different labels are different alerts.

Batches

If you send an array, OpsFusion processes each alert. The request returns 500 only if every alert in the batch fails.

---

Alertmanager Endpoint

To receive alerts from Prometheus Alertmanager, point a webhook receiver at:

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

It uses the same authentication, role requirement, truncation, duplicate handling, and quotas as the standard endpoint. See the Prometheus integration guide for setup.

Item	Behavior
Body	The standard Alertmanager webhook payload. The alerts array is required and holds 1-25 alerts. Other fields (receiver, generatorURL, startsAt, and so on) are ignored.
Per alert	status (firing or resolved), annotations.summary (the title) and annotations.description are required. labels are optional.
Team	Taken from the annotations.ofteamid annotation, then the ofteamid request header. It must be a valid team ID. Otherwise the alert goes to the Default team.
Severity	Taken from the annotations.ofseverity annotation, then the ofseverity request header. 1 or critical is critical, 2 or warning is warning, and anything else is info.
Status	firing opens an alert. Any other status closes it.

---

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
401 Unauthorized	The Authorization header is missing
403 Forbidden	Authentication failed, or the key’s roles don’t allow this endpoint
429 Too Many Requests	Your monthly alert or notification quota is reached
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"
}

See Errors for more on error responses.

Severity Levels

Severity	Value	When to Use
Critical	1	Service down, data loss, security breach
Warning	2	Degraded performance, approaching limits
Info	3	Informational conditions

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

Quotas

Each account has monthly alert and notification quotas. When a quota is reached, the API returns 429 Too Many Requests with a message such as alert quota reached (N) or notification quota reached (N).

Duplicate alerts count toward your quotas. Retrying a 429 won’t succeed until the quota resets, so back off and alert your own team instead.

The “Default” Team

Built-in Fallback Team

Every OpsFusion account includes a special “Default” team that automatically catches alerts sent to unknown team IDs. Its team ID is the same as your account ID. This ensures no alerts are lost due to misconfiguration.

How it works:

• If you send an alert with a well-formed teamId that doesn’t match any team, the alert is automatically assigned to the Default team. A malformed teamId is rejected with a 400.
• 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 a valid team ID)
• Verify severity and status use correct integer values
• Remove any fields that aren’t listed in the request body table
• Make sure the title and description are within the length limits
• Send the Content-Type: application/json header

401 Unauthorized

• The Authorization header is missing or empty

403 Forbidden

• Check that your API key is valid and hasn’t been deleted
• Verify the key is copied in full
• Make sure the account ID in the URL is the account that owns the key
• Ensure the key has the Alert Push or Admin role

Alert went to the wrong team

• Alerts for an unknown team ID are accepted (200) and routed to the Default team. Check the team ID.

429 Too Many Requests

• Your monthly alert or notification quota is reached. Retrying won’t help until the quota resets.
• Consider reducing duplicate alerts, for example by fixing noisy checks

Support

For API support:

• Email: support@opsfusion.cloud
• See API Overview for getting started guide
• See Errors for status codes and causes