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

You can create and manage API keys with granular permissions and sub account access. For details, see API Key Management.

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

Maximum: 100

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.

Results are provided for full days only, starting from midnight. A time range of less than 24 hours gives results for the full day.

For example:

  • A time range of 14:00 - 20:00 yesterday gives results for all of yesterday (midnight to midnight) - a full day.
  • A time range of 14:00 last Tuesday to 14:00 last Wednesday gives results for all of Tuesday and Wednesday - two full days.
  • A time range of 14:00 yesterday to 14:00 today gives results for all of yesterday starting from midnight until the current time today.
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.
  • Midnight is based on Coordinated Universal Time (UTC).
  • 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.