VoIP Spear API

Description

A sentry is an instance of the monitoring softwware that is running on a computer. The sentry software is available for both Windows and Mac operating systems.

Sentry Object

Field Description
id An integer that uniquely identifies the sentry.
name Name of the sentry.
description Description of the sentry.
alert_threshold MOS score below which the sentry starts alerting
custom_id This field can be used to provide a customer identifier for a sentry. Some customers use this for linking the sentry to their internal information systems.
created_at The date and time the sentry was created.
deleted_at The date and time the sentry was cancelled. If this is null, then the sentry has not been deleted/cancelled yet.

{
  "id": 56,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2008-01-01 07:00:00",
  "deleted_at": null,
}
        

Commands

Action Method URL
List your sentries GET /sentries
Show info for an sentry GET /sentries/<sentry_id>
Create a new sentry POST /sentries
Update an sentry PATCH /sentries/<sentry_id>
Delete/cancel sentry DELETE /sentries/<sentry_id>
Recover a deleted sentry PATCH /sentries/<sentry_id>/activate

List your sentries

Usage

GET /sentries

Description

By default, this returns all active sentries for your account. However, you can use the following parameters to constrain the search.

Arguments

name Case-insensitive partial match on the name of the sentry.
ip_address Case-insensitive partial match on the IP address/hostname of the sentry.
custom_id Case-insensitive exact match on the custom ID field.
status Status ("active", "cancelled") of the sentries. Default: "active".
      GET /sentries
      
{
  "collection": [
    {
      "id": 56,
      "name": "My Sentry",
      "description": null,
      "alert_threshold": 3.9,
      "custom_id": "123456789",
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
    },
    {
      "id": 158,
      "name": "Another Sentry",
      "description": null,
      "alert_threshold": 3.9,
      "custom_id": null,
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
    },
    {
      "id": 23395,
      "name": "Yet One More Sentry",
      "description": "This is a description",
      "alert_threshold": 3.9,
      "custom_id": null,
      "created_at": "2017-04-12 09:35:34",
      "deleted_at": null,
    }
  ],
  "metadata": {
    "count": 3
  }
}
      
    

Show info for an sentry

Usage

GET /sentries/<sentry_id>
      GET /sentries/36
      
{
  "id": 23400,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}
      
    

Update an sentry

Arguments

PATCH /sentries/<sentry_id>

The fields you may specify when updating an sentry are similar to creating a new sentry. The only difference is that you cannot change the IP address of the sentry after it is created.

Description

Note that you can optionally define which servers to use for testing this sentry using the argument server_ids[]. You can use codec, interpacket_ms, and num_tests also, however it's not recommended to provide these arguments unless you have an advanced understanding of VoIP testing and how VoIP Spear works.

For more granular control of the tests for your sentry, refer to the VoIP Tests section

Arguments

name The name of the sentry.
description Description for the sentry.
port The port number for the sentry. Most sentries leave this as null.
alert_threshold The threshold below which the sentry goes into alerting state.
category The type of sentry ("ping", "sip", "udp"). Default: null (which is "ping").
server_ids[] (optional) Array of Server ID's for testing this sentry. Note that this is an array so you must pass this value as follows: &server_id[]=1&server_id[]=2
codec (optional) Codec to use for the testing. Default: g711. Options: g711, g723, g729, gsm_fr, gsm_efr, ilbc, g722, speex.
interpacket_ms (optional) Number of milliseconds between packets of each test.
num_tests (optional) Number of individual tests/packets to use for each round of testing.
      PATCH /sentries/23400     args: {"name": "New sentry name" }
      
{
  "id": 23400,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}
      
    

Create new sentry

Usage

POST /sentries

Description

Note that you can optionally define which servers to use for testing this sentry using the argument server_ids[]. You can use codec, interpacket_ms, and num_tests also, however it's not recommended to provide these arguments unless you have an advanced understanding of VoIP testing and how VoIP Spear works.

For more granular control of the tests for your sentry, refer to the VoIP Tests section

Arguments

name The name of this sentry.
description A description for the sentry.
alert_threshold The threshold below which the sentry goes into alerting state.
custom_id A custom ID field which can be any string you like.
server_ids[] (optional) Array of Server ID's for testing this sentry. Note that this is an array so you must pass this value as follows: &server_id[]=1&server_id[]=2
codec (optional) Codec to use for the testing. Default: g711. Options: g711, g723, g729, gsm_fr, gsm_efr, ilbc, g722, speex.
interpacket_ms (optional) Number of milliseconds between packets of each test.
num_tests (optional) Number of individual tests/packets to use for each round of testing.
      POST /sentries     { "ip_address": "1.2.3.4", "name": "My sentry", "alert_threshold": 3.9, "custom_id": "123456789" }
      
{
  "id": 23400,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}
      
    
      

Example with server_ids[] supplied.

POST /sentries { "ip_address": "1.2.3.4", "name": "New sentry", "alert_threshold": null, "server_ids[]", "1", "server_ids[]", "1024" } { "id": 23400, "name": "My Sentry", "description": null, "alert_threshold": null, "custom_id": null, "created_at": "2017-04-17 00:51:52", "deleted_at": null, }

Delete/cancel sentry

Usage

DELETE /sentries/<sentry_id>

Description

Deletes an sentry. Note that the sentry can be recovered after this.

      DELETE /sentries/234232
      
{
  "id": 23400,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": "2017-04-17 01:35:15",
}
      
    

Recover deleted sentry

Usage

PATCH /sentries/<sentry_id>/activate
      PATCH /sentries/234232/activate
      
{
  "id": 23400,
  "name": "My Sentry",
  "description": null,
  "alert_threshold": 3.9,
  "custom_id": "123456789",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}