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.

Arguments

When supplying these arguments, they must be inside a JSON element named "endpoint".

name The name of the endpoint.
description Description for the endpoint.
      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

Arguments

When supplying these arguments, they must be inside a JSON element named "endpoint".

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").
      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,
}
      
    

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,
}