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. |
| 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. |
| server_ids | Array of server ID's for the sentry. |
| alert_threshold | MOS score below which the sentry starts alerting. |
| alert_ids | Array of alert ID's for the sentry. |
{
"id": 56,
"name": "My Sentry",
"description": null,
"custom_id": "123456789",
"created_at": "2008-01-01 07:00:00",
"deleted_at": null,
"server_ids": [78, 910, 1112],
"alert_threshold": 3.9,
"alert_ids": [5]
}
| 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. |
| 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,
"custom_id": "123456789",
"created_at": "2008-01-01 07:00:00",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 3.9,
"alert_ids": [4]
},
{
"id": 158,
"name": "Another Sentry",
"description": null,
"custom_id": null,
"created_at": "2008-01-01 07:00:00",
"deleted_at": null,
"server_ids": [12, 34],
"alert_threshold": null,
"alert_ids": []
},
{
"id": 23395,
"name": "Yet One More Sentry",
"description": "This is a description",
"custom_id": null,
"created_at": "2017-04-12 09:35:34",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 4.0,
"alert_ids": [4]
}
],
"metadata": {
"count": 3
}
}
GET /sentries/<sentry_id>
GET /sentries/36
{
"id": 23400,
"name": "My Sentry",
"description": null,
"custom_id": "123456789",
"created_at": "2017-04-17 00:51:52",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 4.0,
"alert_ids": [4]
}
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. |
| 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. |
| alert_threshold | (optional) The threshold below which the sentry goes into alerting state. |
| alert_ids[] | (optional) Array of Alert ID's for this sentry. Note that this is an array so you must pass this value as follows: &alert_id[]=1&alert_id[]=2. |
Note the link between alert_threshold and alert_ids. If you set alert_threshold
to null, then alert_ids must be empty. If you provide a value for alert_threshold, you
must also provide alert_ids.
POST /sentries { "ip_address": "1.2.3.4", "name": "My sentry", "custom_id": "123456789", "alert_threshold": 3.9, "alert_ids[]", 44 }
{
"id": 23400,
"name": "My Sentry",
"description": null,
"custom_id": "123456789",
"created_at": "2017-04-17 00:51:52",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 3.9,
"alert_ids": [44]
}
Example with server_ids[] supplied.
POST /sentries { "ip_address": "1.2.3.4", "name": "New sentry", "server_ids[]", "1", "server_ids[]", "1024" }
{
"id": 23400,
"name": "My Sentry",
"description": null,
"custom_id": null,
"created_at": "2017-04-17 00:51:52",
"deleted_at": null,
"server_ids": [1, 1024],
"alert_threshold": null,
"alert_ids": []
}
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. |
| 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. |
| alert_threshold | (optional) The threshold below which the sentry goes into alerting state. |
| alert_ids[] | (optional) Array of Alert ID's for this sentry. Note that this is an array so you must pass this value as follows: &alert_id[]=1&alert_id[]=2. |
Note the link between alert_threshold and alert_ids. If you set alert_threshold
to null, then alert_ids must be empty. If you provide a value for alert_threshold, you
must also provide alert_ids.
PATCH /sentries/23400 args: {"name": "New sentry name" }
{
"id": 23400,
"name": "My Sentry",
"description": null,
"custom_id": "123456789",
"created_at": "2017-04-17 00:51:52",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 4.0,
"alert_ids": [4]
}
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,
"custom_id": "123456789",
"created_at": "2017-04-17 00:51:52",
"deleted_at": "2017-04-17 01:35:15",
"server_ids": [],
"alert_threshold": 4.0,
"alert_ids": [4]
}
PATCH /sentries/<sentry_id>/activate
PATCH /sentries/234232/activate
{
"id": 23400,
"name": "My Sentry",
"description": null,
"custom_id": "123456789",
"created_at": "2017-04-17 00:51:52",
"deleted_at": null,
"server_ids": [],
"alert_threshold": 4.0,
"alert_ids": [4]
}
