InstaWP API

Overview

All of InstaWP's APIs are organized around REST. If you’ve used RESTful APIs before, many of the concepts here will be familiar to you. Each resource has a unique URL, and HTTP verbs are used to specify actions you want to perform on each resource. All request and response bodies, including errors, are encoded in JSON. (exception for file upload)

With our API you can:

Create, update, delete and retrieve detailed information about InstaWP resources (Sites, Templates, etc.).
Perform queries or searches.
And lots more…

API VERSION

The current version of our APIs is v2, so the base URL will always look something like this – "https://app.instawp.io/api/v2"

Authentication

You will need to obtain an API key from your account. To create an API key click here.



Click Create, you will be provided with an API key which can be saved for later use.

Please do not share your API keys (especially if they are read-write). Make sure to use them inside "secrets" section of Github or similar tools or in a .env file.

HTTP Methods

We support these HTTP methods - GET, POST, PUT, PATCH, DELETE.

GET - For simple retrieval of information about resources, you should use the GET method. The information you request will be returned to you as a JSON object. Any request using the GET method is read-only and will not affect any of the objects you are querying.

POST - To create a new object, your request should specify the POST method. The POST request includes all of the attributes necessary to create a new object. When you wish to create a new object, send a POST request to the target endpoint.

PUT - To update the information about a resource in your account, the PUT method is available. Like the DELETE Method, the PUT method is idempotent.

PATCH - Some resources support partial modification. In these cases, the PATCH method is available. Unlike PUT which generally requires a complete representation of a resource, a PATCH request is a set of instructions on how to modify a resource updating only specific attributes.

DELETE - To destroy a resource and remove it from your account, the DELETE method should be used. This will remove the specified object if it is found. If it is not found, the operation will return a response indicating that the object was not found.

Parameters

There are two different ways to pass parameters in a request with the API.

Modify Data

When passing parameters to create or update an object, parameters should be passed as a JSON object containing the appropriate attribute names and values as key-value pairs. When you use this format, you should specify that you are sending a JSON object in the header. This is done by setting the Content-Type header to application/json. This ensures that your request is interpreted correctly.

curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"site_name": "sophine"}' -X POST "https://app.instawp.io/api/v2/sites"

Read Data

When passing parameters to filter response on GET requests, parameters can be passed using standard query attributes. In this case, the parameters would be embedded into the URI itself by appending a ? to the end of the URI and then setting each attribute with an equal sign. Attributes can be separated with a &.

curl -H "Authorization: Bearer $TOKEN" -X GET "https://app.instawp.io/api/v2/sites?type=reserved"

Localization

We support two languages – English and Spanish (more to be added soon).

The content is still returned in the English language. Multi-language is used to get the messages of API response according to the language passed in the request header. You should specify the language as a header (X-localization) in the request. The name of the language should be according to ISO 15897.

curl -X $HTTP_METHOD -H "X-localization: es" "https://app.instawp.io/api/v2/$OBJECT"

Error and Response Handling

HTTP STATUSES

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

In general, if the status returned is in the 200 range, it indicates that the request was fulfilled successfully and that no error was encountered.

Return codes in the 400 range typically indicate that there was an issue with the request that was sent. Among other things, this could mean that you did not authenticate correctly, that you are requesting an action that you do not have authorization for, that the object you are requesting does not exist, or that your request is malformed.

If you receive a status in the 500 range, this generally indicates a server-side problem. This means that we are having an issue on our end and cannot fulfill your request currently.

Response Codes

If an API call is successful, it returns a "200 OK" response. If there is an exception, an error code along with an exception message is returned. Here is the list of response codes and their meaning –

Response Code with Description

200 OK - This is the status code for a successful API call. Check the message body to find JSON data if the API call is expected to return a result.
201 Created - This is the status code for a successful API call when we create a new resource. Check the message body to find JSON data if the API call is expected to return a result.
202 Accepted - Indicates that the request has been accepted for processing, but the processing has not been completed; in fact, processing may not have started yet.
400 Bad Request - The message body on the request is not as per API specification. Make sure that the content type is set to "application/json" and the JSON body has correct attribute names and structure.
401 Unauthorized - The API call was made with invalid access cre dentials. Check your bearer token.
404 Not Found - The API could not be found. Please check the API signature (syntax).
429 Too Many Requests - Indicates the user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server Error - The API called failed. There could be many reasons for it. Check the exception message to get more details. In the case of a 500 Internal Server Error, a JSON response body that will provide information about the error also appears.

DateTime Format

Please note that the DateTime format for all date fields is yyyy-MM-dd HH:mm:ss.

The date should always be in UTC. You’ll have to convert the DateTime from your time-zone to UTC. The time is in 24-hour format and there is a space between the date and time. For example, 2018-10-05 14:34:53 is a valid value that represents 5th Oct 2018, 2:34:53 PM in UTC.

Date-time fields returned in the API response will contain milliseconds and have the format yyyy-MM-dd HH:mm:ss.SSS However, the date-time format accepted for all input/update calls is yyyy-MM-dd HH:mm:ss (must not contain milliseconds).

Rate Limits

There are limits on the number of API calls you can make. When you reach the limit, the InstaWP API will throw an API rate limit exception and will stop processing any more requests until a certain amount of time has passed.

We impose a rate limit to prevent overloading the servers and to maintain a high quality of service. Rate limit establishes availability for a wider range of users by ensuring that single users or regions don’t dominate the concurrent connections to a server. This ensures that more users with more diverse needs can connect to a wider collection of servers, increasing the user base and potential revenue.

Every API Response includes a status field (a boolean) that indicates the operation status, message field indicates the success or error message of the operation. The API Response also has a data field that either has a single object in case of a single resource (eg., getting details of a single site) and can have multiple objects(s) for getting a list of resources (eg., getting a list of all sites). The API Response also has a meta field that gives information about pagination.

💡 Did you know - With the help of API token, any guest user (even without InstaWP account) can create website from their shared template. Learn about Create shared template using APIs.

Updated on: 10/04/2024