Incapsula API Reference

Incapsula provides customers and partners with the ability to manage accounts and sites via an API.

In this topic:

Overview

The API has the following characteristics:

  • Requests are HTTP POST.
  • Parameters are specified in the request body in HTML form style. For example:

    param1=value1&param2=value2
  • All requests are in SSL.
  • Response content is provided as a JSON document.
  • UTF-8 encoding is always used.

General request structure

Authentication

In order to use the API, the client must be authenticated by Incapsula. Authentication is accomplished using two request parameters, an API ID and an API Key. For example:

api_id=12345&api_key=48d69342-eaec-44cf-8a5c-56c4ff1cd5e8

To generate an API ID and Key:

  1. Log into your my.incapsula.com account and go to Management > Account Settings.
  2. Under API Settings, click New API Key, and copy the details in the popup window.

Once the pop up window with the generated ID & key is closed, you'll no longer be able to retrieve the key. If lost, you can reset or revoke the key, and replace it with a new one. For more details, see Account Settings.

Account and site identifiers

Most API operations operate on a specific account or site. Use the following parameters to specify the account or site to operate on:

Name Description
account_id
Numeric identifier of the account to operate on.
site_id
Numeric identifier of the site to operate on.

Pagination

Some API operations may return a list of objects. Use the following parameters to enable paging:

Name Description Optional
page_size

The number of objects to return in the response.

Default: 50

Yes
page_num

The page to return starting from 0.

Default: 0

Yes

Time range specification

Some operations require the user to specify a time range. This is done via the time_range parameter, which accepts the following values:

Name Description
today
Retrieve data from midnight today until the current time.
last_7_days
Retrieve data from midnight of 7 days ago until the current time.
last_30_days
Retrieve data from midnight of 30 days ago until the current time.
last_90_days
Retrieve data from midnight of 90 days ago until the current time.
month_to_date
Retrieve data from midnight of the first day of the month until the current time.
custom
Specify a custom time range using two additional parameters: start and end.
Note:
  • If a time range is not specified, today is selected by default.
  • All dates should be specified as number of milliseconds since midnight 1970 (UNIX time * 1000). For details, see http://en.wikipedia.org/wiki/Unix_time.
  • The available time ranges depend on the customer subscription plan.

General response structure

Every response contains the following fields in the returned JSON document:

Name Description
res
The numeric result code for the operation. A result code of 0 indicates success.
res_message
The textual representation of the result code (for example: "OK" - for success).
debug_info
General information which is not strictly required for using the API, but is helpful to have.

For example:

{
    "res": 0,
    "res_message": "OK",
    "debug_info": {}
}
General error codes:
Code Description Comment
1 Unexpected error The server has encountered an unexpected error.
2 Invalid input Input missing or incorrect.
4 Operation timed-out or server unavailable The server is not available or reached a time-out while processing the operation.
9411 Authentication missing or invalid Authentication parameters missing or incorrect.
9403 Unknown/unauthorized account_id The specified account is unknown or client is not authorized to operate on it.
9413 Unknown/unauthorized site_id The specified site is unknown or client is not authorized to operate on it.
9414 Feature not permitted Feature is not available on account's plan.
9415 Operation not allowed The requested operation is not allowed.