NAV Navbar
Star

Check your mailbox Something went wrong. Please contact support

Navbar
cURL C# Go Node.js PHP Python Ruby Java
Management

Subscription Mgmt - REST API

General

This secrion describing general information about the Subscription Management API.

Security

The use of the encryption is required. We are using protocols that are considered the best security practices.

Standards and conventions

This section represents used standards and conventions across all documents and API's.

Variables naming

All variables are named using the Snake case (or snake_case) naming convention. This means that words are separated by a single underscore _ character, no spaces are used, and letters are lowercase.

Time

For all input and output time values ISO 8601 standard is used.

Format specifier Description
yyyy The year as a four-digit number.
MM The month, from 01 through 12.
dd The day of the month, from 01 through 31.
HH The hour, using a 24-hour clock from 00 to 23.
mm The minute, from 00 through 59.
ss The second, from 00 through 59.
fff The milliseconds in a date and time value.
fffffff The ten millionths of a second in a date and time value.

Input time values are parsed using the following formats as far as possible:

Output time values are formatted using the following patterns:

  1. yyyy-MM-ddTHH:mm:ss.fffffffZ
  2. yyyy-MM-dd

Endpoints

Enviroment Encryption Value
Production Yes https://www.coinapi.io/api/

Authorization

To use resources that require authorized access, you will need to provide an API key to us when making HTTP requests.

There are 2 methods for passing the API key to us, you only need to use one:

  1. Custom authorization header named X-CoinAPI-Key
  2. Query string parameter named apikey

Custom authorization header

You can authorize by providing additional custom header named X-CoinAPI-Key and API key as its value.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY, then the authorization header you should send to us will look like:

X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY

Query string authorization parameter

You can authorize by providing an additional parameter named apikey with a value equal to your API key in the query string of your HTTP request.

Assuming that your API key is 73034021-THIS-IS-SAMPLE-KEY and that you want to request all exchange rates from BTC asset, then your query string should look like this:

GET /v1/exchangerate/BTC?apikey=73034021-THIS-IS-SAMPLE-KEY

HTTP Requests

Each HTTP request must contain the header Accept: application/json as all our responses are in JSON format.

We encourage you to use the HTTP request header Accept-Encoding: deflate, gzip for all requests. This will indicate to us that we can deliver compressed data to you which on your side should be decompressed transparently.

HTTP Success

Successful HTTP responses have the status code 200 and the body in a format according to documentation of the requested resource.

HTTP Errors

Error message is returned in JSON structured like this:

{
    "message": "Invalid API key"
}

All HTTP requests with response status codes different to 200 must be considered as failed and you should expect additional JSON inside the body of the response with the error message encapsulated inside it as shown in the example. We use the following error codes:

Error Code Meaning
400 Bad Request -- There is something wrong with your request
401 Unauthorized -- Your API key is wrong
403 Forbidden -- Your API key doesnt't have enough privileges to access this resource
429 Too many requests -- You have exceeded your API key rate limits
550 No data -- You requested specific single item that we don't have at this moment.

Output data format

By default we are using JSON output data format for all of our endpoints, you can control format of data by using output_format variable in query string parameters.

URL Parameters

Parameter Type Description
output_format string Output data format (optional, default value is json, possible values are json, xml or csv)
csv_include_header bool Ignore header line in CSV output? (optional, default value is true, true to include CSV header line, false otherwise)
csv_include_quotes bool Encapsulate strings with quotes in CSV output? (optional, default value is false, true to encapsulate all strings with ", false to leave them unquoted)
csv_exclude_col string Comma delimited list of column names to ignore in CSV output (optional, by default all columns are included)
csv_set_delimiter string Character that will be used as column delimiter in CSV output (optional, default value is ;)
csv_set_dec_mark string Character that will be used as decimal separator in CSV output (optional, default value is .)
csv_set_timeformat string Format for datetime type in CSV output or unix for unix timestamp (optional, default value is yyyy-MM-ddTHH:mm:ss.fffffffZ)
csv_set_newline string New line type (optional, default value is unix, possible values win, mac, unix)

Subscriptions

This section describes calls related to your API subscription.

REST usage GET

curl https://www.coinapi.io/api/subscriptions/usage/rest/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"
var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/rest/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/rest/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/rest/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)
const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();
import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/rest/history")
}
require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/rest/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/rest/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "date": "2018-11-01",
    "requests": 691
  },
  {
    "date": "2018-10-31",
    "requests": 11779
  },
  {
    "date": "2018-10-30",
    "requests": 4275
  },
  {
    "date": "2018-10-29",
    "requests": 3495
  },
  {
    "date": "2018-10-27",
    "requests": 11
  },
  {
    "date": "2018-10-26",
    "requests": 56
  }
]

Get the historical daily number of requests used.

HTTP Request

  1. GET /api/subscriptions/usage/rest/history
  2. GET /api/subscriptions/usage/rest/history?date_start={date_start}
  3. GET /api/subscriptions/usage/rest/history?date_end={date_end}
  4. GET /api/subscriptions/usage/rest/history?date_start={date_start}&date_end={date_end}

URL Parameters

Parameter Type Description
date_start datestring Starting date (optional)
date_end datestring Ending date (optional)
limit int Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable Description
date Date of the period
requests Requests used in the period

Stream usage GET

curl https://www.coinapi.io/api/subscriptions/usage/stream/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"
var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/stream/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/stream/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/stream/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)
const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();
import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/stream/history")
}
require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/stream/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/stream/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
[
  {
    "date": "2018-11-01",
    "total_connections_days": 2.3030973986550922,
    "total_gigabytes_delivered": 40.2514768460354349,
    "total_messages_delivered": 45286100
  },
  {
    "date": "2018-10-31",
    "total_connections_days": 1.9242,
    "total_gigabytes_delivered": 46.42245,
    "total_messages_delivered": 224425
  }
]

Get the historical streaming usage log.

HTTP Request

  1. GET /api/subscriptions/usage/stream/history
  2. GET /api/subscriptions/usage/stream/history?date_start={date_start}
  3. GET /api/subscriptions/usage/stream/history?date_end={date_end}
  4. GET /api/subscriptions/usage/stream/history?date_start={date_start}&date_end={date_end}

URL Parameters

Parameter Type Description
date_start datestring Starting date (optional)
date_end datestring Ending date (optional)
limit int Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable Description
date Date of the period
total_connections_days Amount of connections days used in specific day
total_gigabytes_delivered Amount of gigabytes of data delivered in specific day
total_messages_delivered Number of messages delivered in specific day

Stream usage (detailed) GET

curl https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"
var client = new RestClient("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
import requests
url = 'https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)
const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();
import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
}
require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/usage/stream/detailed/history")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "time_start": "2018-11-01T11:27:22.2855249Z",
    "time_end": "2018-11-01T11:31:02.4891607Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 1845207,
    "bytes_recv": 297,
    "msgs_send": 1245,
    "msgs_recv": 1,
    "msgs_lost": 0
  },
  {
    "time_start": "2018-11-01T11:27:21.5511460Z",
    "time_end": "2018-11-01T11:31:01.7393780Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 1842283,
    "bytes_recv": 297,
    "msgs_send": 1243,
    "msgs_recv": 1,
    "msgs_lost": 0
  },
  {
    "time_start": "2018-11-01T11:15:46.6302944Z",
    "time_end": "2018-11-01T11:26:41.5077182Z",
    "protocol_name": "WebSocket",
    "ip_client": "127.0.0.1",
    "bytes_send": 5488624,
    "bytes_recv": 297,
    "msgs_send": 3822,
    "msgs_recv": 1,
    "msgs_lost": 0
  }
]

Get the historical streaming detailed usage log.

HTTP Request

  1. GET /api/subscriptions/usage/stream/detailed/history
  2. GET /api/subscriptions/usage/stream/detailed/history?time_start={time_start}
  3. GET /api/subscriptions/usage/stream/detailed/history?time_end={time_end}
  4. GET /api/subscriptions/usage/stream/detailed/history?time_start={time_start}&time_end={time_end}

URL Parameters

Parameter Type Description
time_start timestring Log starting time in ISO 8601 (optional)
time_end timestring Log ending time in ISO 8601 (optional)
limit int Amount of items to return (optional, mininum is 1, maximum is 100000, default value is 100, if the parameter is used then every 100 output items are counted as one request)

Output variables

Variable Description
time_start Time on which data streaming was started
time_end Time on which data streaming was ended
protocol_name Protocol type used for data distribution (WebSocket/FIX)
ip_client Client IP address from which connection was established
bytes_send Bytes send on the connection by the CoinAPI
bytes_recv Bytes received on the connection by the CoinAPI
msgs_send Messages send on the connection by CoinAPI
msgs_recv Messages received on the conncetion by CoinAPI
msgs_lost Messages lost cased by the TCP client backpressure

Cancel GET

curl https://www.coinapi.io/api/subscriptions/cancel \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"
var client = new RestClient("https://www.coinapi.io/api/subscriptions/cancel");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/cancel');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
import requests
url = 'https://www.coinapi.io/api/subscriptions/cancel'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)
const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();
import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/cancel")
}
require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/cancel")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/cancel")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

Flag subscription for the cancelation at the end of the current billing period.

HTTP Request

  1. GET /api/subscriptions/cancel?confirm=yes

Reactivate GET

curl https://www.coinapi.io/api/subscriptions/reactivate \
  --request GET
  --header "X-CoinAPI-Key: 73034021-THIS-IS-SAMPLE-KEY"
var client = new RestClient("https://www.coinapi.io/api/subscriptions/reactivate");
var request = new RestRequest(Method.GET);
request.AddHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY");
IRestResponse response = client.Execute(request);
<?php
$request = new HttpRequest();
$request->setUrl('https://www.coinapi.io/api/subscriptions/reactivate');
$request->setMethod(HTTP_METH_GET);
$request->setHeaders(array(
  'X-CoinAPI-Key' => '73034021-THIS-IS-SAMPLE-KEY'
));

try {
  $response = $request->send();
  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
?>
import requests
url = 'https://www.coinapi.io/api/subscriptions/reactivate'
headers = {'X-CoinAPI-Key' : '73034021-THIS-IS-SAMPLE-KEY'}
response = requests.get(url, headers=headers)
const https = require('https');

var options = {
  "method": "GET",
  "hostname": "coinapi.io",
  "path": "/v1/orderbooks/current",
  "headers": {'X-CoinAPI-Key': '73034021-THIS-IS-SAMPLE-KEY'}
};

var request = https.request(options, function (response) {
  var chunks = [];
  response.on("data", function (chunk) {
    chunks.push(chunk);
  });
});

request.end();
import (
  "gopkg.in/resty.v0"
)

func main()
{
    resp, err := resty.R().
      SetHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY").
      Get("https://www.coinapi.io/api/subscriptions/reactivate")
}
require 'uri'
require 'net/http'

url = URI("https://www.coinapi.io/api/subscriptions/reactivate")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["X-CoinAPI-Key"] = '73034021-THIS-IS-SAMPLE-KEY'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.coinapi.io/api/subscriptions/reactivate")
  .post(body)
  .addHeader("X-CoinAPI-Key", "73034021-THIS-IS-SAMPLE-KEY")
  .build();

Response response = client.newCall(request).execute();

Remove the subscription cancelation flag.

HTTP Request

  1. GET /api/subscriptions/reactivate
Was this section helpful?
StatusPage: