Using the HTTP API

The HTTP API allows you to send and receive requests from your server to Wix.

How it Works:

Every call to the HTTP API shares a common entry point: openapi.wix.com/v1

To enable Wix to identify the site and application calling the HTTP API, all HTTP calls must be authenticated. Wix uses an HMAC scheme and requires HTTPS to ensure the integrity and authenticity of each request.

When issuing a HTTP request, your request must be signed with your secret key, and include the request parameters either as query parameters or as headers.

Request Parameters

HeaderDescription
x-wix-application-idApp ID
x-wix-instance-idApp Instance ID: the unique ID per user per site
x-wix-timestampTimestamp in UTC format (ISO 8601); for example, 2013-07-01T08:07:40.802Z. Valid for one minute only
x-wix-signatureHMACSHA-256 signature, generated using the app secret key and the request headers

Signature

Every call is sent with a digital signature in the x-wix-signature header, for authentication purposes.

To encode the signature:

  1. Sort all request parameters by parameter name (in ascending alphanumeric order) and concatenate their values with only a line break (n) as a separator. The request parameters include the following:
    a. Query parameters, all except for the signature parameter
    b. All headers with the prefix x-wix-, except the x-wix-signature header. For multivalue parameters, values should be trimmed and concatenated using a comma (,).
  2. Concatenate, in the following order, and separate by a line break (n)
    a. HTTP method, converted to uppercase
    b. HTTP request’s URL path, without the host
    c. All values from the sorted request parameters (the output of #1)
    d. The request body
  3. Compute the HMACSHA-256 of the combined information using your app secret key.
  4. Encode the hash to a Base64 string.
  5. Add the signature as the query parameter signature or as the x-wix-signature header.

Working with Data

For endpoints that return large amounts of data, the HTTP API employs a technique called cursoring to navigate large sets of data. Cursoring separates result data into pages of a fixed size and provides a way to move forwards and backwards through these pages.

For initial calls to APIs that support cursors, it is possible to either omit the cursor parameter or to pass a cursor with the value of -1. Each call to a cursoring-enabled endpoint will return a JSON object that includes a cursor to the previous page, a cursor to the next page and an array containing the data for the current page. If either the next or previous page does not exist, the value of the cursor will be 0.

All cursors are associated with the initial data request and expire within 30 minutes.

Data cursor:

Copy
1
{
2
nextCursor: <cursor>,
3
previousCursor: <cursor>,
4
results: [
5
<<items>>
6
]
7
}

Errors

All API errors from the HTTP API use standard HTTP error codes, as well as a JSON response containing information relevant to the error.

Wix API Error Example

Copy
1
{
2
errorCode : 400,
3
message : "Missing endpoint version number."
4
}

Standard API Errors

HTTP Error CodeDescriptionArea
400Bad request. Authentication credentials may be missingAuthentication
400Missing endpoint version numberVersioning
403Bad authentication credentialsAuthentication
404Invalid endpoint or version number specifiedVersioning
408Timestamp expired on the request, please submit again with a fresh signatureAuthentication
Was this helpful?
Yes
No