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'.
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",
  "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.
deleted If this parameter is present, the list of endpoints will include deleted/cancelled endpoints.
      GET https://voipspear.com/endpoints
      
[
  {
    "id": 6,
    "ip_address": "21.18.57.21",
    "port": null,
    "name": "Toronto01",
    "description": "this is a test description",
    "category": "ping",
    "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",
    "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",
    "created_at": "2017-04-12 09:35:34",
    "deleted_at": null,
  }
]
      
    

Show info for an endpoint

Usage

GET /endpoints/<endpoint_id>
      GET https://voipspear.com/endpoints/36
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "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 https://voipspear.com/endpoints/23400     args: {"endpoint":{"name": "New endpoint name"}}
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint name",
  "description": null,
  "category": "ping",
  "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.
ip_address The IP address (or FQDN) of the endpoint.
description A description for the endpoint.
      POST https://voipspear.com/endpoints     { "endpoint": { "ip_address":"1.2.3.4", "name":"New endpoint" } }
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}
      
    

Cancel endpoint

Usage

DELETE /endpoints/<endpoint_id>
      DELETE https://voipspear.com/endpoints/234232
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "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 https://voipspear.com/endpoints/234232/activate
      
{
  "id": 23400,
  "ip_address": "1.2.3.4",
  "port": null,
  "name": "New endpoint",
  "description": null,
  "category": "ping",
  "created_at": "2017-04-17 00:51:52",
  "deleted_at": null,
}