Server API

REST API calls allowing for connecting to Instabot services

📘

Don't have an Instabot account yet?

Start your free trial today!

Overview

The Server API is a set of REST API calls that allows developers to integrate Instabot portal functionality into existing administrative systems.

Contents

  1. Using the Instabot Server API
  2. Request Format
  3. Response Format
  4. Error Handling
  5. Authentication

1. Using the Instabot Server API

📘

All URIs below are relative to https://api.instabot.io/v1

All calls to this endpoint require both the API key, and the API Master key available in the Instabot portal.

Both API keys must be present in the header of every request to the API endpoint:

curl https://api.instabot.io/v1 \
    -X GET \
    -H "X-Instabot-Api-Key: {API_KEY}"
    -H "Authorization: X-Instabot-Master-Api-Key {API_MASTER_KEY}

All data to be posted to the API, or returned by the API must be in JSON format. API responses will always be structured in the following way:

  • apiStatusCode - API status code
  • apiStatusMessage - message providing additional information about error. Not provided if request completed successfully
  • data - response data. For example, if details about a user is requested from API, then the data about that user will be returned in data field. data will not be present if the request returns with an error, or no data is expected in the return
{
    "apiStatusCode" : "Success",
    "data": {
        "version" : "2016-05-01",
        "applicationName":"Sample App"
    }
}

2. Request Format

Instabot API uses JSON format for input and output data. All POST/PUT requests to the API must set the Content-Type HTTP header to application/json.
To identify your application to the API, the X-Instabot-Api-Key HTTP header must always contain your Instabot API key.


3. Response Format

The Instabot server API will always responds with the following JSON structure:

  • apiStatusCode - API status code
  • apiStatusMessage - message providing additional information about error. Not provided if the request completed successfully
  • data - response data. For example, if details about a user is requested from API, then the data about that user will be returned in "data" field. Not provided if request returned with an error or if data response not required for specific method.
{
    "apiStatusCode" : "Success",
    "data": {
        "version":"2015-08-01"
    }
}
{
    "apiStatusCode": "ApiKeyInvalid",
    "apiStatusMessage": "API Key is invalid."
}

4. Error Handling

The Instabot server API uses standard HTTP codes to report the status of the request. Additionally, the response body contains a status code and message providing more descriptive information about the request. List of API status codes:

Status Code

HTTP Code(s)

Description

Success

200, 201

Operation completed successfully

AuthenticationFailed

401

Authentication information not provided, or is incorrect

AccessDenied

403

Operation was denied because of insufficient access rights

ObjectNotFound

404

Object not found

BadRequest

400

Attempt to execute operation in an invalid context

ObjectAlreadyExists

400

Attempt to create object with the same unique name or id

BadParameterValue

400

Some required parameters are omitted in request, or incorrect

ApiKeyInvalid

400

API Key provided within the request was not recognized as valid

CustomDomainNameAlreadyUsed

400

Custom domain name already used in the system

UnidentifiedError

500

Unidentified system error occurred

For example, if you call an API method that requires the API key and/or authentication, but do not provide the required keys:

curl https://api.instabot.io/v1/usersession \
    -X GET

then the API will reply with an error:

{  
   "apiStatusCode":"AccessDenied",
   "apiStatusMessage":"User not authorized for this action."
}

5. Authentication

The API itself only provides access to the API. To get additional rights to API methods, it is required to pass authentication information within the call. Instabot leverages a standard ”Authorization” HTTP header for that purpose. Please note that you still need to send the API keys within each request to specify context of the application.

No Authentication

X-Instabot-Api-Key: {API_KEY}

When only API Key is passed only limited number of API calls available

User Authentication

X-Instabot-Api-Key: {API_KEY}
Authorization: X-Instabot-User-Session {USER_SESSION_KEY}

User session key is returned after logging in as user into API. Provides access to user specific methods.

Master API Key Authentication

X-Instabot-Api-Key: {API_KEY}
Authorization: X-Instabot-Master-Api-Key {MASTER_API_KEY}

Master API Key can be obtained from application settings screen in the Instabot portal. Provide access to all API methods with administrative access