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.
| 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,
}
| 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 |
GET /sentries
By default, this returns all active sentries for your account. However, you can use the following parameters to constrain the search.
| 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
}
}
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,
}
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.
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
| 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,
}
POST /sentries
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
| 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 /sentries/<sentry_id>
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",
}
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,
}
