API Reference

The Webinstant API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Authentication

Authenticate your account when using the API by including your username and API key in the request. You can get your API key in your dashboard. Do not share your secret API key in publicly accessible areas such GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Once you have your Webinstant API key, you will need to base64 encode it using a terminal window as well as your username to use it with the API. The command you will use to base64 it, is as follows: echo "USERNAME:PASSWORD" | base64

You will then replace USERNAME:PASSWORD with your username and newly generated API key. For example: echo "my@username.com:hbQWQBtJEu5h3J2nGR37LdNs" | base64

Once your username and API key are base64 encoded, you will be able to make a simple REST API call using the terminal window. You will need to authorize the request using your newly created base64 encoded access token.

Errors

Webinstant uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a wrong domain provided, etc.), and codes in the 5xx range indicate an error with Webinstant's servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a site is not created), we return a 402 error code.

• code

  The error code returned. Can be: rest_no_route, rest_authentication_error, rest_domain_error, rest_template_error, user_email_error, site_name_error, or site_id_error.

• message
  optional

  A human-readable message providing more details about the error.

• data
  optional

  Data containing extra information about the error. It also contains status returning the HTTP response code.

Versioning

Until the API has reached a stable state, we will at times, make some backwards-incompatible changes.

We are doing versioning via the URL, which means that with the current version, you would access the API by making a request to https://api.webinstant.io/v1/

You will be notified before any breaking changes happen.

Rate limits

Rate limiting of the API is primarily on a per-user basis — or more accurately described, per user access token. If a method allows for 15 requests per rate limit window, then it allows 15 requests per window per access token.

15 minute windows

Rate limits are divided into 15 minute intervals. All endpoints require authentication, so there is no concept of unauthenticated calls and rate limits.

HTTP headers and response codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

• X-Rate-Limit-Limit: the rate limit ceiling for that given endpoint
• X-Rate-Limit-Remaining: the number of requests left for the 15 minute window
• X-Rate-Limit-Reset: the remaining window before the rate limit resets, in UTC epoch seconds

When an user exceeds the rate limit, the API will return a HTTP 429 “Too Many Requests” response code.
To better predict the rate limits available, consider periodically using GET /rate_limit_status. Like the rate limiting HTTP headers, this resource’s response will indicate the rate limit status for the current user.

Tips to avoid rate limitations

The tips below are there to help you code defensively and reduce the possibility of being rate limited. Some application features that you may want to provide are simply impossible in light of rate limiting, especially around the freshness of results.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don’t try to call the Webinstant API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

Sites

The site endpoint is the main endpoint that you will be dealing with. It is the endpoint you use to create, update or delete your websites. You have parameters to set the path of the element to be amended, the post_id for when doing multiple updates across different pages and of course, the value to be applied. The site endpoint will return a an object indicating the successfulness of the action.

The site object

• domain
  optional

  This acts as a unique domain name and identifier for the site that is composed by a full sub-domain of the type: mysite.webinstant.io.

• url
  string

  The URL of the publicly-accessible website for this site.

• title
  string

  The site title that is displayed on the browser as a part of the meta <title> tag.

• registered
  timestamp

  The date and time the site was created.

• plan
  string

  The plan to which the site is subscribed to.

• template
  string

  The name of the template the site is based on; the current available templates are: bloc, module and travelco.

• settings
  array of objects

  All fields available for the site. These are the values that can actually be updated and allows to update the options that relates to the site. For example, site title, favicon, etc.

• pages
  array of objects

  This is a list of all pages available for the site.

• styles
  array of objects

  A list of all available styles that can be updated for the entire site. These are based on CSS declarations. These will affect the styling of elements site-wide.

Create a new site

Creates a new website. The action of creating a website is internally composed of several processes, some of which are resource-intensive, (e.g.: importing images) as a result the total elapsed time of the request might be significantly higher if we compare it with the average HTTP request times. The maximum number of websites a user can create is determined by the plan the user is subscribed to.

• name

  A unique name that will be prepended to .webinstant.io and that will become the identifier and primary domain name for the created site, this will result on a full unique sub-domain of the type: mysite.webinstant.io.

• title

  The default website title that will be displayed on the browser as a part of the meta <title> tag.

• template

  The name of the template the website will be based on, the current available templates are: bloc, module and travelco.

Returns

The newly created site object if the call succeeded.

If the maximum number of sites have been reached, the request will return a sites_limit_reached error, and the site creation won't go into effect.

Retrieve an existing site

Retrieves the details of an existing site, supplying the unique site domain name.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing full sub-domain of the type: mysite.webinstant.io.

Returns

Returns a site object if a valid identifier was provided.

Update a site

Updates an existing site to match the specified settings and / or styles parameters. Any parameters not provided will be left unchanged.

Note that each of both parameters must be an array of field objects.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• settings
  optional

  A list of field objects that can be attached to a site object and that will update all the specified site options accordingly. This argument refers to the settings attribute of the site object that can be gathered by retrieving an existing site.

• styles
  optional

  Also a list of field objects that can be attached to a site object and that will update all the specified website styles accordingly. This argument refers to the styles attribute of the site object that can be gathered by retrieving an existing site.

List all sites

Returns a list of the user sites. The sites are returned sorted by creation date, with the least recently created sites appearing first.

• expired
  optional

  Return also expired sites.

Delete a site

Permanently deletes a site. All media, elements, pages and fields will also be permanently deleted.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

Site Settings

The settings belonging to a site. You can update, retrieve, as well as list all settings related to a site.

Retrieve an existing site setting

Retrieves the details of an existing page, supplying the unique site domain name and a page identificator.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

Returns

Returns a page object if a valid domain and page was provided.

Update a site setting

Updates an existing setting to match the specified path parameter. 

• path
  required

  An unique internal identifier expressed in a form of a path that refers to the element intended to be updated. This path is based on an internal interpretation of a hierarchical array of objects. Every single element on the website has a specific path that can be updated, including styling, content and layout. The fields attribute of the site object contains a human-readable list of the most used paths which are available, however you can specify any additional paths. We are in the process of providing a way to help identifying which paths correspond to which elements on the website.

• value
  required

  This will overwrite the current value of the element specified in the path attribute.

Returns

The newly updated field object if the call succeeded.

List all site settings

Returns a list of all settings of a site.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

Pages

The pages belonging to a site. You can update, retrieve, as well as list all pages related to a site. Pages are identified by a unique ID.

The page object

• id
  integer

  Unique page identificator within the site context.

• slug
  string

  The unique location slug for this page.

• name
  string

  The name for this page, as it appears in the navigation bar.

• status
  string

  Disable and hide, or enable and show the page in the navigation bar. Status values can be either publish or draft.

• url
  string

  The URL of the publicly-accessible website for this page.

• settings
  array of field objects

  A list of field objects belonging to a page object. These are the updatable settings of the page.

• fields
  array of field objects

  Also a list of field objects belonging to page object. These are the updatable fields of the page.

Retrieve an existing page

Retrieves the details of an existing page, supplying the unique site domain name and a page identificator.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

Returns

Returns a page object if a valid domain and page was provided.

Update a page

Updates an existing page to match the specified settings and / or fields parameters. Any parameters not provided will be left unchanged.

Note that each of both parameters must be an array of objects with path and value.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

• settings
  optional

  A list of field objects that can be attached to a page object and that will update all the specified site options accordingly. This argument refers to the settings attribute of the page object that can be gathered by retrieving an existing page.

• fields
  optional

  Also a list of field objects that can be attached to a page object and that will update all the specified website styles accordingly. This argument refers to the fields attribute of the page object that can be gathered by retrieving an existing page.

Returns

The newly updated page object if the call succeeded.

List all pages

Returns a list of all pages on a site. The pages are returned sorted by creation date, with the least recently created sites appearing first.

• as_list
  optional

  Return a simplified list of pages containing only id and name for each object on the list. Available values are 1 or 0.

Page Settings

The settings belonging to a page. You can update, retrieve, as well as list all settings related to a page.

Retrieve an existing site setting

Retrieves the details of an existing page, supplying the unique site domain name and a page identificator.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

Returns

Returns a page object if a valid domain and page was provided.

Update a page setting

Updates an existing setting to match the specified path parameter.

• path
  required

  An unique internal identifier expressed in a form of a path that refers to the element intended to be updated. This path is based on an internal interpretation of a hierarchical array of objects. Every single element on the website has a specific path that can be updated, including styling, content and layout. The fields attribute of the site object contains a human-readable list of the most used paths which are available, however you can specify any additional paths. We are in the process of providing a way to help identifying which paths correspond to which elements on the website.

• value
  required

  This will overwrite the current value of the element specified in the path attribute.

Returns

The newly updated field object if the call succeeded.

List all page settings

Returns a list of all settings of a page.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

Fields

The fields belonging to a page. You can update, retrieve, as well as list all fields related to a page.

The field object

• domain
  string

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  integer

  A unique page identificator.

• path
  string

  An unique internal identifier expressed in a form of a path that refers to an element on the site. This path is based on an internal interpretation of a hierarchical array of objects. Every single element on the website has a specific path that can be updated, including styling, content and layout. The settings attribute of the site object contains a human-readable list of the most used paths which are available, however you can specify any additional paths. We are in the process of providing a way to help identifying which paths correspond to which elements on the website.

• name
  string

  A human-readable value intended to help recognising elements by a short description of what the field is intended for.

• value
  string

  The current value of the element specified in the path attribute.

Retrieve an existing field

Retrieves the details of an existing site, supplying the unique site domain name.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing full sub-domain of the type: mysite.webinstant.io.

Returns

Returns a site object if a valid identifier was provided.

Update a field

Updates an existing field to match the specified path parameter.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

• path
  required

  An unique internal identifier expressed in a form of a path that refers to the element intended to be updated. This path is based on an internal interpretation of a hierarchical array of objects. Every single element on the website has a specific path that can be updated, including styling, content and layout. The fields attribute of the site object contains a human-readable list of the most used paths which are available, however you can specify any additional paths. We are in the process of providing a way to help identifying which paths correspond to which elements on the website.

• value
  required

  This will overwrite the current value of the element specified in the path attribute.

Returns

The newly updated field object if the call succeeded.

List all fields

Returns a list of all fields of a page.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• page
  required

  A unique page identificator.

Returns

Returns a list with all fields belonging to a page. Each entry in the array is a separate object. If no more fields are available, the resulting array will be empty. This request should never return an error.

Styles

The styles belonging to a site. You can update, retrieve, as well as list all styles related to a site.

Retrieve an existing style

Retrieves the details of an existing site, supplying the unique site domain name.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing full sub-domain of the type: mysite.webinstant.io.

Returns

Returns a site object if a valid identifier was provided.

Update a style

Updates an existing style to match the specified path parameter.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

• path
  required

  An unique internal identifier expressed in a form of a path that refers to the element intended to be updated. This path is based on an internal interpretation of a hierarchical array of objects. Every single element on the website has a specific path that can be updated, including styling, content and layout. The fields attribute of the site object contains a human-readable list of the most used paths which are available, however you can specify any additional paths. We are in the process of providing a way to help identifying which paths correspond to which elements on the website.

• value
  required

  This will overwrite the current value of the element specified in the path attribute.

Returns

The newly updated field object if the call succeeded.

List all styles

Returns a list of all styles of a site. Styles apply site-wide.

• domain
  required

  A unique domain name that acts as the identifier and primary domain for the site, this must be an existing sub-domain of the type: mysite.webinstant.io.

Returns

Returns a list with all styles belonging to a site. Each entry in the array is a separate object. If no more styles are available, the resulting array will be empty. This request should never return an error.