VoIP Spear API: Users
Introduction Getting Started Users Endpoints VoIP Tests Servers

Description

An endpoint is the computer/phone/router/etc you would like to monitor. An endpoint is really just an IP address (or hostname) that VoIP Spear can test to.

By default, endpoints are created with 'ping' testing (which uses ICMP for testing). VoIP Spear is also able to do SIP testing (via SIP OPTIONS requests) or UDP testing (using the VoIP Spear probe). If you would like to do SIP or UDP testing of your endpoints, please contact VoIP Spear for more information.

Endpoint Object

Field Description
id An integer that uniquely identifies the endpoint.
name Name of the endpoint.
ip_address The IP address (or hostname) of the endpoint.
port The port the tests should go to. For ping/ICMP testing, this port is not used.
description Description of the endpoint.
category 'ping', 'sip', or 'udp'.
alert_threshold MOS score below which the endpoint starts alerting
created_at The date and time the endpoint was created.
deleted_at The date and time the endpoint was cancelled. If this is null, then the endpoint has not been deleted/cancelled yet. 

{
  "id": 6,
  "ip_address": "216.18.5.21",
  "port": null,
  "name": "NYC Office",
  "description": null,
  "category": "ping",
  "alert_threshold": 3.9,
  "created_at": "2008-01-01 07:00:00",
  "deleted_at": null,
}

Commands

Action Method URL
List your endpoints GET /endpoints
Show info for an endpoint GET /endpoints/<endpoint_id>
Create a new endpoint POST /endpoints
Update an endpoint PATCH /endpoints/<endpoint_id>
Delete/cancel endpoint DELETE /endpoints/<endpoint_id>
Re-activate a cancelled endpoint PATCH /endpoints/<endpoint_id>/activate

List your endpoints

Usage

GET /endpoints

Description

By default, this returns all active endpoints 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 endpoint.
ip_address Case-insensitive partial match on the IP address/hostname of the endpoint.
status Status ("active", "cancelled") of the endpoints. Default: "active". 
      GET /endpoints
      
{
  "collection": [
    {
      "id": 6,
      "ip_address": "21.18.57.21",
      "port": null,
      "name": "Toronto01",
      "description": "this is a test description",
      "category": "ping",
      "alert_threshold": null,
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
    },
    {
      "id": 8,
      "ip_address": "42.177.23.176",
      "port": null,
      "name": "Julia Home",
      "description": null,
      "category": "ping",
      "alert_threshold": null,
      "created_at": "2008-01-01 07:00:00",
      "deleted_at": null,
    },
    {
      "id": 23395,
      "ip_address": "1.2.3.4",
      "port": null,
      "name": "Test endpoint",
      "description": null,
      "category": "ping",
      "alert_threshold": 3.1,
      "created_at": "2017-04-12 09:35:34",
      "deleted_at": null,
    }
  ],
  "metadata": {
    "count": 3
  }
}

Show info for an endpoint

Usage

GET /endpoints/<endpoint_id> 
      GET /endpoints/36
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "alert_threshold": 4.2,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}

Update an endpoint

Arguments

PATCH /endpoints/<endpoint_id>

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

Description

Note that you can optionally define which servers to use for testing this endpoint 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 endpoint, refer to the VoIP Tests section

Arguments

name The name of the endpoint.
description Description for the endpoint.
port The port number for the endpoint. Most endpoints leave this as null.
alert_threshold The threshold below which the endpoint goes into alerting state.
category The type of endpoint ("ping", "sip", "udp"). Default: null (which is "ping").
server_ids[] (optional) Array of Server ID's for testing this endpoint. 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 /endpoints/23400     args: {"name": "New endpoint name" }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint name",
  "description": null,
  "category": "ping",
  "alert_threshold": 3.8,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}

Create new endpoint

Usage

POST /endpoints

Description

Note that you can optionally define which servers to use for testing this endpoint 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 endpoint, refer to the VoIP Tests section

Arguments

name The name of this endpoint.
description A description for the endpoint.
ip_address The IP address (or FQDN) of the endpoint.
port The port number for the endpoint. Most endpoints leave this as null.
alert_threshold The threshold below which the endpoint goes into alerting state.
category The type of endpoint ("ping", "sip", "udp"). Default: null (which is "ping").
server_ids[] (optional) Array of Server ID's for testing this endpoint. 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 /endpoints     { "ip_address": "1.2.3.4", "name": "New endpoint", "alert_threshold": 4.0 }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "alert_threshold": 4.0,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}
      
    
      
Example with server_ids[] supplied.


      POST /endpoints     { "ip_address": "1.2.3.4", "name": "New endpoint", "alert_threshold": 4.0, "server_ids[]", "1", "server_ids[]", "1024" }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "alert_threshold": 4.0,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}

Cancel endpoint

Usage

DELETE /endpoints/<endpoint_id> 
      DELETE /endpoints/234232
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "alert_threshold": 3.5,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": "2017-04-17 01:35:15",
}

Re-activate endpoint

Usage

PATCH /endpoints/<endpoint_id>/activate 
      PATCH /endpoints/234232/activate
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "alert_threshold": null,
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}