# Rawstream Platform API The Rawstream API allows you to easily integrate Rawstream CloudDNS data into your own applications such as monitoring and dashboards. - HTTPS-based API - JSON output You can use the API to retrieve: - Account status - Networks and key properties - Traffic data - Domain data - Category data Getting started is simple: all you need is a an API Key. To retrieve your API key, log in to the Rawstream Dashboard, then click *Settings* > *Accounts*, then scroll to the *Rawstream API* section. ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&account" $ {"status-code":200,"status":"OK","data":{"product":"Rawstream DNS Service","quantity":10,"subscription-status-code":3,"subscription-status":"Valid","subscription-ends":"2017-10-18","subscription-days-left":257}} ``` ##### Prerequisites You will need a Rawstream account. [Sign up here](https://app.rawstream.com/signup). ##### API Status This is the first release of the API. Expect bugs. Please report to support@rawstream.com. Thanks! - API Version: *0.1* - API Last Update: *2017-02-02* - Document Last Update: *2017-02-03* ### Account Status ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&account" ``` Returns key account information: - subscription status code - number of seats - date subscription expiration - number of days left to subscription expiration ### List of networks ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-list" ``` Returns an array of networks and their properties: - network ID - name - IP address - timezone offset in hours - whether the network is enabled (1) or not (0) - Google SafeSearch enabled (1) or not (0) - Youtabe SafeSearch enabled (1) or not (0) ### Update Network IP ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-update-ip&netid=NETWORKID&newip=1.2.3.4" ``` Updates the IP of a network with a dynamic public IP address. By default the IP of the caller is used. You can optionally specify the IP. Only networks that are configured as dynamic networks can be updated. The update fails if the network is not defined as dynamic, or if the IP address is already in use by any other network. Allow up to 60 seconds for the updated IP to propagate. __Parameters__ - netid: network ID. -1 is not valid. - newip: Network's new IP ### Daily Traffic ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-traffic&netid=-1&date=2017-02-02&numdays=2" ``` Returns number of DNS requests for the indicated days on a daily and per-hour basis. __Parameters__ - netid: -1 for aggregate network data, or network ID - date: yyyy-mm-dd format. Optional. Default is today - numdays: Optional. Default is 1. Max is 7 __Returns__ ![alt text][network-daily-traffic] [network-daily-traffic]: http://data.rawstream.com/docs/images/network-daily-traffic.png ### Daily Domains ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-domains&netid=-1&date=2017-02-02&numdays=2" ``` Returns number of DNS requests per domain for the given days. __Parameters__ - netid: -1 for aggregate network data, or network ID - date: yyyy-mm-dd format. Optional. Default is today - numdays: Optional. Default is 1. Max is 7 - filtered: Optional. If set returns only the filtered domains. __Returns__ ![alt text][network-daily-domains] [network-daily-domains]: http://data.rawstream.com/docs/images/network-daily-domains.png ### Hourly Domains ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-hourly-domains&netid=-1&date=2017-02-02" ``` Returns number of DNS requests per domain per hour for a specific day. __Parameters__ - netid: -1 for aggregate network data, or network ID - date: yyyy-mm-dd format. Optional. Default is today - numdays: Optional. Default is 1. Max is 7 - filtered: Optional. If set returns only the filtered domains. __Returns__ ![alt text][network-hourly-domains] [network-hourly-domains]: http://data.rawstream.com/docs/images/network-hourly-domains.png ### Daily Categories ```sh $ curl -s "https://data.rawstream.com/?key=YOURSECRETAPIKEY&network-daily-categories&netid=-1&date=2017-02-02&numdays=2" ``` Returns number of DNS requests per domain per hour for a specific day. __Parameters__ - netid: -1 for aggregate network data, or network ID - date: yyyy-mm-dd format. Optional. Default is today - numdays: Optional. Default is 1. Max is 7 __Returns__ ![alt text][network-daily-categories] [network-daily-categories]: http://data.rawstream.com/docs/images/network-daily-categories.png