HTTP API

If this is your first time interacting with our API, please read the rest of this page before viewing the detailed endpoint documentation for one of the services below:

Service Endpoints

Auth Endpoints Endpoints for using Ionic Auth, our user authentication service
Deploy Endpoints Endpoints for using Ionic Deploy, our live updating service
Push Endpoints Endpoints for using Ionic Push, our push notification service

The HTTP API gives you programmatic access to our services. We try our best to be RESTful, making use of resource-based URLs, status codes, methods (GET, POST, DELETE, etc.), and JSON for requests and responses. This makes it easy to use vanilla HTTP clients in your backend for powerful API interaction.

Requests to our API (https://api.ionic.io) must be made securely over HTTPS.

Required Headers

Vocabulary

Here are some of the terms found in our HTTP API documentation:

Authentication

Our API uses JSON Web Tokens (JWTs) to authenticate protected endpoints.

Generating your API Token

You can create an API token for your app by navigating to Settings › API Keys in the Dashboard and clicking New Token:

Authenticating Requests

Authenticate your requests by using the Authorization header.

In the following examples, fill in the following:

API_TOKEN Your generated API Token
// Example requires the use of the `request` library
// https://www.npmjs.com/package/request

var request = require("request");
var token = 'API_TOKEN'

var options = {
  method: 'GET',
  url: 'https://api.ionic.io/auth/test',
  headers: {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
  }
};

request(options, function(err, response, body) {
  if (err) throw new Error(err);
  console.log(body);
});
<?php

$curl = curl_init();
$token = "API_TOKEN";

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.ionic.io/auth/test",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer $token",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
# Example requires the `requests` python module:
# https://pypi.python.org/pypi/requests/

import requests

url = "https://api.ionic.io/auth/test"
token = "API_TOKEN"

payload = ""
headers = {
    'Authorization': "Bearer %s" % token,
    'Content-Type': "application/json"
}

response = requests.get(url, data=payload, headers=headers)

print(response.text)
curl --request GET \
  --url https://api.ionic.io/auth/test \
  --header 'Authorization: Bearer API_TOKEN' \
  --header 'Content-Type: application/json' \
GET /auth/test HTTP/1.1
Host: api.ionic.io
Authorization: Bearer API_TOKEN
Content-Type: application/json

Conventions

Response Structure

Every response is JSON (with the exception of 204 responses, which have an empty body). The returned JSON will have the same base structure:

data
mixed

For 2xx responses, this field will exist. It will be an object representing the requested resource or an array of resources.

error
object

For 4xx and 5xx responses, this object will exist. It may contain additional fields.

type
string

The type of error that occurred.

message
string

A quick summary about the error that occurred.

link
string
(url)

A link to our docs to get more information about the error.

meta
object

Additional information about the request, response, or API. It may contain additional fields.

status
integer
(int32)

HTTP Status Code

version
string
(semver)

API Version

request_id
string
(uuid)

Request Reference ID

Pagination

For collection endpoints that support it, pagination allows you to use pages to loop through your resources. You can paginate responses using the following query params:

page
integer
(int32) Page number. The first page of pagination is a value of 1.
page_size
integer
(int32) Number of items to return per page. Defaults to 25. Most endpoints have a max size of 100 items.

Extra Fields

Some endpoints offer the ability to return additional data as requested. The endpoint documentation will list the additional fields you can request, but they are always requested using the following query param:

fields
string[]
Additionally requested fields

Services

    API

      General