API Documentation

Authentication

To access the API, you'll need to create a personal access token. This can be done by logging in, clicking your profile icon in the top right corner, and going to Personal Access Tokens.

Personal access tokens will have the same rights as the user that generated the token.

Accounts

Accounts are users that have access to an organization.

List Accounts

Lists all accounts under an organization.

GET /api/v1/{organizationId}/accounts

Request:

curl https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/accounts \
  -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
  -G

Response:

{
    "count": 1,
    "values": [
        {
            "id": "13e6cc47-cd44-4818-8d12-eef5659a70fd",
            "name": "Tester",
            "emailAddress": "test@test.com",
            "phoneNumber": null
        }
    ]
}

Alerts

Alerts are received from monitoring systems and applications. When an alerts comes into MetaAlerts, they are processed by the routing rules before becoming incidents.

Create Alert

Creating an alert requires first setting up an alerting endpoint under a team's configuration. The UI will provide a URL for the alerting endpoint.

POST /api/v1/alerts/{alertingEndpointId}

Request Body:

{
  "payload": {
    "summary": "Example alert on host1.example.com",
    "timestamp": "2015-07-17T08:42:58.315+0000",
    "source": "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-prod-003",
    "severity": "info",
    "component": "postgres",
    "group": "prod-datapipe",
    "custom_details": {
      "ping time": "1500ms",
      "load avg": 0.75
    }
  },
  "dedup_key": "samplekeyhere",
  "images": [
    {
      "src": "https://https://metaalerts.io/assets/images/logo-words.png",
      "href": "https://example.com/",
      "alt": "Example text"
    }
  ],
  "links": [
    {
      "href": "https://example.com/",
      "text": "Link text"
    }
  ],
  "event_action": "trigger",
  "client": "Sample Monitoring Service",
  "client_url": "https://monitoring.example.com"
}
Parameter Location Required Description
alertingEndpointID URL True The unique ID for that team to receive alerts. Can be created from the UI under the team configuration -> alerting endpoints.
event_action Request Body True The type of event. Can be trigger, acknowledge or resolve.
dedup_key Request Body True Deduplication key for correlating triggers and resolves. The maximum permitted length of this property is 255 characters.
payload.summary Request Body True A brief text summary of the event, used to generate the summaries/titles of any associated alerts. The maximum permitted length of this property is 1024 characters.
client_url Request Body True The client ID associated with the MetaAlerts instance.
payload.source Request Body False The unique location of the affected system, preferably a hostname or FQDN.
payload.severity Request Body False The perceived severity of the status the event is describing with respect to the affected system. This can be critical, error, warning or info.
payload.timestamp Request Body False The time at which the emitting tool detected or generated the event.
payload.component Request Body False Component of the source machine that is responsible for the event, for example mysql or eth0
payload.group Request Body False Logical grouping of components of a service, for example app-stack
payload.custom_details Request Body False Additional details about the event and affected system
images Request Body False List of images to include.
links Request Body False List of links to include.

Alert Deduplication

Every alert event has a dedup_key: a string which identifies the alert triggered for the given event. The dedup_key can be specified when submitting the first trigger event that creates an alert.

Submitting subsequent events with the same dedup_key will result in those events being applied to an open alert matching that dedup_key. Once the alert is resolved, any further events with the same dedup_key will create a new alert (for trigger events) or be dropped (for acknowledge and resolve events). Alerts will only be created for events with an event_action of trigger. Acknowledge or resolve events without a currently open alert will not create a new one.

Event Action Behavior

Three actions can be specified in the event_action parameter. Each represents a different type of activity.

Event Action Behavior
trigger A new alert is opened or a trigger log entry is created on an existing alert if one already exists with the same dedup_key.

Use this event action when a new problem has been detected. Additional triggers may be sent when a previously detected problem has occurred again.
acknowledge The incident referenced with the dedup_key will enter the acknowledged state.

While an incident is acknowledged, it won't generate any additional notifications, even if it receives new trigger events.

Use this event action to indicate that someone is presently working on the problem.
resolve The incident referenced with the dedup_key will enter the resolved state.

Once an incident is resolved, it won't generate any additional notifications. New trigger events with the same incident_key / dedup_keyas a resolved incident won't re-open the incident. Instead, a new incident will be created.

Use this event action when the problem that caused the initial trigger event has been fixed.

Response:

{
    "Client": "Sample Monitoring Service",
    "ClientUrl": "https://monitoring.example.com",
    "EventAction": "trigger",
    "DedupKey": "samplekeyhere",
    "Summary": "Example alert on host1.example.com",
    "Source": "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-prod-003",
    "Severity": 1,
    "Timestamp": "2015-07-17T03:42:58",
    "Component": "postgres",
    "Group": "prod-datapipe",
    "CustomDetails": {
        "ping time": [],
        "load avg": []
    },
    "Images": [
        {
            "src": "https://https://metaalerts.io/assets/images/logo-words.png",
            "href": "https://example.com/",
            "alt": "Example text"
        }
    ],
    "Links": [
        {
            "href": "https://example.com/",
            "text": "Link text"
        }
    ],
    "Id": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
    "FriendlyId": "100014",
    "AssignedTeamId": "1cfd2137-f1a7-45a3-b35e-43a19086aab4",
    "ForwardTime": null,
    "History": [
        {
            "id": "eebd8082-fc92-48f9-b33b-f126468963ee",
            "parentId": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
            "accountId": null,
            "summary": "The alert was created.",
            "fieldChanges": [],
            "createdDate": "2022-09-14T22:49:49.374225Z"
        },
        {
            "id": "2f9ef552-62ef-4c91-8295-91d6185db13d",
            "parentId": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
            "accountId": null,
            "summary": "Incident #100015 has been created and associated with the alert.",
            "fieldChanges": [],
            "createdDate": "2022-09-14T22:49:49.5597487Z"
        }
    ],
    "CreatedDate": "2022-09-14T22:49:49.3740207Z",
    "Status": 2
}

Create Email Alert

Email alerts are designed to work with an email provider that forwards incoming messages to an API such as CloudMailin. Documentation on their email structure can be found here: http://docs.cloudmailin.com/http_post_formats/json_normalized/.

POST /thirdparty/email-alerts/{endpointSecretKey}

Request Body:

{
  "headers": {
    "return_path": "from@example.com",
    "received": [
      "by 10.52.90.229 with SMTP id bz5cs75582vdb; Mon, 16 Jan 2012 09:00:07 -0800",
      "by 10.216.131.153 with SMTP id m25mr5479776wei.9.1326733205283; Mon, 16 Jan 2012 09:00:05 -0800",
      "from mail-wi0-f170.google.com (mail-wi0-f170.google.com [209.85.212.170]) by mx.google.com with ESMTPS id u74si9614172weq.62.2012.01.16.09.00.04 (version=TLSv1/SSLv3 cipher=OTHER); Mon, 16 Jan 2012 09:00:04 -0800"
    ],
    "date": "Mon, 16 Jan 2012 17:00:01 +0000",
    "from": "Message Sender <sender@example.com>",
    "to": "Message Recipient<to@example.co.uk>",
    "message_id": "<4F145791.8040802@example.com>",
    "subject": "Test Subject",
    "mime_version": "1.0",
    "content_type": "multipart/alternative; boundary=------------090409040602000601080801",
    "delivered_to": "to@example.com",
    "received_spf": "neutral (google.com: 10.0.10.1 is neither permitted nor denied by best guess record for domain of from@example.com) client-ip=10.0.10.1;",
    "authentication_results": "mx.google.com; spf=neutral (google.com: 10.0.10.1 is neither permitted nor denied by best guess record for domain of from@example.com) smtp.mail=from@example.com",
    "user_agent": "Postbox 3.0.2 (Macintosh/20111203)"
  },
  "envelope": {
    "to": "m9k5x9xez4ct9etedpkzwrpa2fn4smja@alerts.ivedha.com",
    "from": "from@example.com",
    "helo_domain": "localhost",
    "remote_ip": "127.0.0.1",
    "recipients": [
      "m9k5x9xez4ct9etedpkzwrpa2fn4smja@alerts.ivedha.com",
      "another@example.com"
    ],
    "spf": {
      "result": "pass",
      "domain": "example.com"
    },
    "tls": true
  },
  "plain": "Test with HTML.",
  "html": "<html><head>\n<meta http-equiv=\"content-type\" content=\"text/html; charset=ISO-8859-1\"></head><body\n bgcolor=\"#FFFFFF\" text=\"#000000\">\nTest with <span style=\"font-weight: bold;\">HTML</span>.<br>\n</body>\n</html>",
  "reply_plain": "Message reply if found."
}

Get Alert

Get an existing alert by ID.

GET /api/v1/{organizationId}/alerts/{alertId}

Request:

curl https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/alerts/d9cdd6a2-ac8d-4411-b8a2-d478bcd4988c \
    -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
    -G

Response:

{
    "Client": "Sample Monitoring Service",
    "ClientUrl": "https://monitoring.example.com",
    "EventAction": "trigger",
    "DedupKey": "samplekeyhere",
    "Summary": "Example alert on host1.example.com",
    "Source": "monitoringtool:cloudvendor:central-region-dc-01:852559987:cluster/api-stats-prod-003",
    "Severity": 1,
    "Timestamp": "2015-07-17T03:42:58",
    "Component": "postgres",
    "Group": "prod-datapipe",
    "CustomDetails": {
        "ping time": [],
        "load avg": []
    },
    "Images": [
        {
            "src": "https://https://metaalerts.io/assets/images/logo-words.png",
            "href": "https://example.com/",
            "alt": "Example text"
        }
    ],
    "Links": [
        {
            "href": "https://example.com/",
            "text": "Link text"
        }
    ],
    "Id": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
    "FriendlyId": "100014",
    "AssignedTeamId": "1cfd2137-f1a7-45a3-b35e-43a19086aab4",
    "ForwardTime": null,
    "History": [
        {
            "id": "eebd8082-fc92-48f9-b33b-f126468963ee",
            "parentId": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
            "accountId": null,
            "summary": "The alert was created.",
            "fieldChanges": [],
            "createdDate": "2022-09-14T22:49:49.374225Z"
        },
        {
            "id": "2f9ef552-62ef-4c91-8295-91d6185db13d",
            "parentId": "6f4784ee-bfc2-4b85-af4f-2c7040f3ade9",
            "accountId": null,
            "summary": "Incident #100015 has been created and associated with the alert.",
            "fieldChanges": [],
            "createdDate": "2022-09-14T22:49:49.5597487Z"
        }
    ],
    "CreatedDate": "2022-09-14T22:49:49.3740207Z",
    "Status": 2
}

Organizations

Organizations are used to seperate global security settings for a company or part of a company. Within an organization, users will have at least read access to all all alerts and incidents.

List Organizations

Lists all organizations the user has access.

GET /api/v1/organizations

Request:

curl https://metaalerts.io/api/v1/organizations \
  -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
  -G

Response:

{
    "count": 1,
    "values": [
        {
            "id": "cb0225d7-d79b-47b3-aacd-a767fcf5e71c",
            "name": "Test Org"
        }
    ]
}

Services

The Service Directory is a comprehensive listing of all services monitored by Meta Alerts. This directory acts as a central repository, providing teams with quick and easy access to information about each service, including its status, dependencies, and any related alerts. This centralized view aids in faster issue identification and resolution.

List Services

List all the services under an organization.

GET /api/v1/{organizationId}/services
Parameter Type Location Required
OrganizationId Unique ID URL True

Request:

curl https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/services \
  -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
  -G

Response:

{
    "count": 2,
    "values": [
        {
            "id": "1661d1f5-745f-4896-be82-025c1f4d31e6",
            "name": "Service A"
        },
        {
            "id": "b7b491f2-9025-4882-860a-c3356f507ee0",
            "name": "Service B"
        }
    ]
}

Create Service

Creates a new service under an organization

POST /api/v1/{organizationId}/services
Parameter Type Location Required
OrganizationId Unique ID URL True
Name String Request Body True

Request:

curl -X POST
    -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
    -d '{ "name": "Service X" }' \
    https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/services

Response:

{
    "id": "ecaa542e-4f40-4780-9987-acaccabcd708",
    "name": "Service X"
}

Teams

Teams support systems and services and have their own on-call schedules, escalation policies, and routing rules.

List Teams

List all the teams under an organization.

GET /api/v1/{organizationId}/teams
Parameter Type Location Required
OrganizationId Unique ID URL True
Name String Request Body True

Request:

curl https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/teams \
  -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
  -G

Response:

{
    "count": 2,
    "values": [
        {
            "id": "1661d1f5-745f-4896-be82-025c1f4d31e6",
            "name": "Team A",
            "slug": "team-a"
        },
        {
            "id": "b7b491f2-9025-4882-860a-c3356f507ee0",
            "name": "Team B",
            "slug": "team-b"
        }
    ]
}

Create Team

Creates a new team under an organization

POST /api/v1/{organizationId}/teams

Request:

curl -X POST
    -header "token: KtBeWkZMsgKgW62A3GchnKDphBgkeXPf" \
    -d '{ "name": "Support Team" }' \
    https://metaalerts.io/api/v1/13e6cc47-cd44-4818-8d12-eef5659a70fd/teams

Response:

{
    "id": "ecaa542e-4f40-4780-9987-acaccabcd708",
    "name": "Support Team",
    "slug": "support-team"
}