Skip to content

Introduction

Our API is still undergoing construction but this page will outline each of the API methods which are available to you.

  • All requests are made using HTTP.
  • All responses will be returned in JSON.
  • The HTTP verb doesn't matter but POST is recommended.
  • Authentication information is provided in HTTP headers.
  • HTTP status codes can be ignored as the status is provided in the standard JSON response. Most requests will return a 200 OK with the exception of a 500 Internal Server Error.
  • The API implements a number of actions which are split into controllers. The documentation is split into the same hierarchy and each controller has it's own section and each action has its own page.

URL

API requests should be made to the following URL and replacing controller & action with the appropriate values for your request.

https://talk.telcom.io/api/v2/controller/action

User Agent

A User-Agent header is recommended but not required. Including such a header will help us help you when debugging any issues you might have when making API requests.

API Limits

API access is currently unrestricted however limits will be imposed in the future.

Parameters

To send parameters to an API action, you must encode them in a JSON hash and send them in the params HTTP parameter. For example, your HTTP body might look like this:

params={"username":"alex"}

Authentication

To authenticate a request to the API, you need to send a couple of authentication headers, to obtain as shown below:

  • X-Auth-Token
  • X-Auth-Secret

To obtain these credentials, head to Advanced > API access in the portal.

Responses

Most responses from the API will be returned as JSON. You can determine the content type using the HTTP Content-Type header. For JSON responses, this will be application/json.

Every request will include a JSON payload similar to this one:

{
  "status":"success",
  "time":1.3,
  "flags":{},
  "data":"..."
}

The status attribute includes the status of the request and can be one of the following values:

  • success - the request was successfully performed
  • not-found - a resource which was requested could not be found
  • error - a generic error message related to your request. The body of these errors will always contain a code and message attribute with details of the error which has been encountered.
  • access-denied - access to the requested action was not permitted
  • parameter-error - the parameters provided were not suitable for this action
  • validation-error - a resource could not be created/updated/removed due to a validation error. This is usually accompanied by errors in the data attribute.
  • internal-server-error - an error outside of your control occurred. Please report these to the team if they persist.