Server Requirements
Builder installation / update
On-Premises
Plugin installation
API documentation
Add-ons documentation
For developers
Change Log
API documentation → Builder

Create session (SSO) available since version 4.0.0 / 3.7.23 Cloud On-Premises

Site.pro Builder is a session-based software. It means that it cannot be opened for a customer directly in browser but instead you need to get unique session URL for that customer using this API method.

Note: If you are running one of hosting panels, for which Site.pro provides installable plugin, like cPanel, Plesk, etc., then an implementation of this API is not required. It should be used only as a fallback if you use a custom hosting solution, for which Site.pro does not provide an integration.

To open builder you need to call API URL by posting JSON object with information about user, if all went successfully API will return JSON object with URL you will need to redirect client to, if error occurs API will return JSON object with error message. All request to API require HTTP Basic Authorisation. Username and password for API Authorisation can be found inside your brand on licenses page after you login to your account. All documentation on how to make requests to API and some request examples are below.

[API URL will appear after you or sign up]
https://site.pro/api/requestLogin
HTTP Basic
[API Username will appear after you or sign up]
[API Password will appear after you or sign up]
POST
application/json
application/json

Currently builder supports the following publication types:

  • external [download PHP code sample] – uses FTP account for files publication. You need to provide FTP account details in API request, belonging to an appropriate website.
  • internal [download PHP code sample] – uses your API endpoint for sending .zip file link to your server. Your API endpoint must download that .zip file and unzip it on an appropriate website hosting. You need to provide your API endpoint URL in API request.
  • http – uses HTTP connections to your API endpoint for files publication. Your API endpoint must handle each request for file creation, file deletion, folder creation and files listing of an appropriate directory. You need to provide API endpoint in API request.
  • ssh – uses SSH connection for files publication. You need to provide SSH account details in API request (supports both password and SSH keys).
  • local On-Premises only – uses file system directly for publication. Works only when on-premises builder and target website are located on the same server.

Click here to see how "external" publishing works in more details.

JSON Object Properties:

Required:

  • String – "external"
  • String – "internal"
  • String – "http"
  • String – "ssh"
  • String – "local"
  • String – Client domain name. This field acts as a website identifier in builder. Make sure it is the same for one unique website. Do not pass different values for one website (for example "www" and "non-www" domain versions), otherwise the website will not be found in builder. You can also pass numeric ID for this parameter as website identifier in builder. Then we recommend to add extra parameter "baseDomain". Please see more information about it below.
  • String – Client FTP connection username.
  • String – Client SSH connection username.
  • String – Client FTP connection password.
  • String – Client SSH connection password (not needed if using SSH keys).
  • String – Client document root directory, relative to FTP account root folder (e.g. "/public_html").
  • String – Full path to website document root.
  • String – Full path to website document root.
  • String – IP address of client's server.
  • String – Your API endpoint URL.
  • String – Your API endpoint URL (it must include website identifier on your hosting).
  • Number – Website/User ID on your end. It will be passed during your API endpoint call as one of parameters during site publication.
  • String – HTTP Basic Authorisation username to call API endpoint URL.
  • String – HTTP Basic Authorisation password to call API endpoint URL.

Note: Starting from builder version 3.7.379 properties "username", "password", "uploadDir" and "apiUrl" may be skipped when calling this API method not for the first time for the same domain. If they are skipped builder will take their values from the last session where these properties were known.

Optional:

  • String – Language 2 letter code (ex. "en", "ru", ...) to open builder in.
  • String – Hosting plan identifier, will be used for correct builder plan detection.
  • String – Product name identifier, will be used for correct builder plan detection.
  • Array of String – Set of addon names, will be used for correct builder plan detection.
  • String – Real client's domain name. We recommend to specify this parameter if it differs from what is specified for "domain". This parameter is used in URLs of website sitemap generation.
  • String – URL to image to use as builder logo (if not set will be taken from brand).
  • String – URL to image to use as builder logo on mobile devices (if not set will be taken from brand).
  • String – URL to image/icon to use as builder favicon (if not set will be taken from brand).
  • String – Title to use for builder (if not set will be taken from brand).
  • Boolean – Do not allow users to remove builder logo from their websites (if not set will be taken from brand).
  • String – URL to place on builder logo in users website.
  • String – Custom identifier accessible in builder plugins.
  • String – Custom templates path (absolute or relative). If set then will be used for loading templates instead of default path (on-premises only since v3.7.230)
  • String – Page ID to open in builder. (on-premises only since v3.7.345)
  • String – Required only when using remote API endpoint of User registration from Public Demo builder
  • Boolean – If set to true response will contain additional two properties: loginHash and builderApiUrl
  • Boolean – If set to true then migration to v4 builder dialog will be suppressed
  • String – User identifier on your platform (recommended for "Revenue Share" model). Used for a better detection of user's upgrade plan. If not specified, then upgrade plan will be applied only to a single website, identified by parameter "domain".
  • String – User email on your platform (recommended for "Revenue Share" model). Used for invoice issuing for payments for user upgrade plan.

Return Object Properties:

  • String – Url to redirect client to (only on success)
  • String – Hash that may be used with website controlling API calls (only on success when request property more is set to true)
  • String – Base API url that should be used for website controlling API calls (only on success when request property more is set to true)
  • Object – Error description object (only on error). Error object structure:
    • String – Text describing the error

API endpoint implementation for internal publication type

During site publication builder will make periodic requests to your API endpoint. The request details are the following:

API endpoint implementation for http publication type

During site publication builder will make periodic HTTP requests to your API endpoint. The request details are the following:

API endpoint URL
HTTP Basic
Value of parameter "username" passed to builder API call
Value of parameter "password" passed to builder API call
POST/GET
application/x-www-form-urlencoded
application/x-www-form-urlencoded, application/octet-stream
application/json
application/json, none

The publication starts with making POST request to URL API endpoint + /zyro/action and providing zip archive of generated client's website. With this request builder sets the following POST parameters:

  • String – URL to zip file containing website generated files. This zip must be downloaded and extracted to client's hosting.
  • Number – Value of parameter "resellerClientAccountId" passed to builder API.
  • String – Value of parameter "domain" passed to builder API.
  • String – Value of parameter "hostingPlan" passed to builder API (if was set).

API endpoint return result (JSON format):

  • Object – (required if error is not returned) Result description object with structure:
    • String – (required if error is not returned) ID of publication process for further process identification in next builder requests. You can pass any non-empty value here.
  • String – (optional) Error message in case if your endpoint cannot process the publication request.

If endpoint returns error then publication stops in builder and error message in shown to the client which you provide in the response.

After getting successful response from endpoint (with no error) builder starts periodically sending GET requests to API endpoint to determine what status the publication of the site is on your end. It makes request to URL API endpoint + /zyro/action/[id] where [id] is a value returned in endpoint POST request.

During builder GET requests API endpoint must return the following result (JSON format):

  • Object – Result description object with structure:
    • String – (required) It can be one of these:
      • PENDING – the process has not yet started on your end.
      • EXECUTING – the process is being executed on your end.
      • FAILED – the process failed on your end.
      • FINISHED – the process has been complete on your end.
    • String – (optional) Error message if status = FAILED.

The builder will make GET requests to API endpoint every 5 seconds until it receives status "FINISHED" or "FAILED". If the publication lasts for more than 2 hours then GET requests and publication stop and builder will show "operation timed out" error message for client.

This process let's you use queue for publication processes. It can be convenient if you have many customers and there can be many publication processes started at one time then the zip downloading and extraction can slow down the server.
If you want making publication without queue then you can do this by extracting zip file at once on builder POST request and responding to builder first GET request with status "FINISHED".

Note:
Your API endpoint URL must support extra arguments. For example if your endpoint is http://myhostingsite.com/api/publish-site then it also must be accessible via URL http://myhostingsite.com/api/publish-site/zyro/action and http://myhostingsite.com/api/publish-site/zyro/action/[id] from which you will need to retrieve publication process ID.

Your API endpoint must catch and process the following HTTP requests from builder:

Put file

Should create (or update) the specified file on the server with the content of the request body.

Request:

API endpoint URL + / [file path]
HTTP Basic
Value of parameter "username" passed to builder API call
Value of parameter "password" passed to builder API call
POST
application/octet-stream

Response:

  • 200 – OK.
  • 403 – Access denied.

Delete file

Should delete the specified file on the server.

Request:

API endpoint URL + / [file path] ?delete=1
HTTP Basic
Value of parameter "username" passed to builder API call
Value of parameter "password" passed to builder API call
GET

Response:

  • 200 – OK.
  • 403 – Access denied.

Create directory

Should create (if does not exist) the specified directory on the server.

Request:

API endpoint URL + / [directory path] ?mkDir=1
HTTP Basic
Value of parameter "username" passed to builder API call
Value of parameter "password" passed to builder API call
GET

Response:

  • 200 – OK.
  • 403 – Access denied.

Get directory files listing

Should return files listing of the specified directory on the server.

Request:

API endpoint URL + / [directory path] ?list=1
HTTP Basic
Value of parameter "username" passed to builder API call
Value of parameter "password" passed to builder API call
GET
application/json

Response:

  • 200 – OK.

    Return Object Properties:

    • Array of Objects – list of files, where each represents the following object:
      • String name – File name
      • Boolean isDir – true of false indicating if the file is a directory
      • Number size – (optional) File size in bytes
      • String size – (optional) File modification time (of format "YYYY-MM-DD HH:ii:ss")
  • 403 – Access denied.

Request Example:

POST /api/requestLogin HTTP/1.1
Host: 
Authorization: Basic W0FQSSBVc2VybmFtZSB3aWxsIGFwcGVhciBhZnRlciB5b3UgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLWxvZ2luLXRyaWdnZXIiPmxvZyBpbjwvYT4gb3IgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLXJlZ2lzdGVyLXRyaWdnZXIiPnNpZ24gdXA8L2E+XTpbQVBJIFBhc3N3b3JkIHdpbGwgYXBwZWFyIGFmdGVyIHlvdSA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tbG9naW4tdHJpZ2dlciI+bG9nIGluPC9hPiBvciA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tcmVnaXN0ZXItdHJpZ2dlciI+c2lnbiB1cDwvYT5d
Content-Type: application/json

{
   "type": "external",
   "domain": "test.com",
   "apiUrl": "11.22.33.44",
   "lang": "en",
   "username": "test.com FTP username",
   "password": "test.com FTP password",
   "uploadDir": "/public_html"
}
		
POST /api/requestLogin HTTP/1.1
Host: 
Authorization: Basic W0FQSSBVc2VybmFtZSB3aWxsIGFwcGVhciBhZnRlciB5b3UgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLWxvZ2luLXRyaWdnZXIiPmxvZyBpbjwvYT4gb3IgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLXJlZ2lzdGVyLXRyaWdnZXIiPnNpZ24gdXA8L2E+XTpbQVBJIFBhc3N3b3JkIHdpbGwgYXBwZWFyIGFmdGVyIHlvdSA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tbG9naW4tdHJpZ2dlciI+bG9nIGluPC9hPiBvciA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tcmVnaXN0ZXItdHJpZ2dlciI+c2lnbiB1cDwvYT5d
Content-Type: application/json

{
   "type": "internal",
   "domain": "test.com",
   "apiUrl": "http://myhostingsite.com/api/publish-site",
   "resellerClientAccountId": 1234,
   "lang": "en"
}
		
POST /api/requestLogin HTTP/1.1
Host: 
Authorization: Basic W0FQSSBVc2VybmFtZSB3aWxsIGFwcGVhciBhZnRlciB5b3UgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLWxvZ2luLXRyaWdnZXIiPmxvZyBpbjwvYT4gb3IgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLXJlZ2lzdGVyLXRyaWdnZXIiPnNpZ24gdXA8L2E+XTpbQVBJIFBhc3N3b3JkIHdpbGwgYXBwZWFyIGFmdGVyIHlvdSA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tbG9naW4tdHJpZ2dlciI+bG9nIGluPC9hPiBvciA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tcmVnaXN0ZXItdHJpZ2dlciI+c2lnbiB1cDwvYT5d
Content-Type: application/json

{
   "type": "http",
   "domain": "test.com",
   "apiUrl": "http://myhostingsite.com/api/publish-site/123/",
   "lang": "en"
}
		
POST /api/requestLogin HTTP/1.1
Host: 
Authorization: Basic W0FQSSBVc2VybmFtZSB3aWxsIGFwcGVhciBhZnRlciB5b3UgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLWxvZ2luLXRyaWdnZXIiPmxvZyBpbjwvYT4gb3IgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLXJlZ2lzdGVyLXRyaWdnZXIiPnNpZ24gdXA8L2E+XTpbQVBJIFBhc3N3b3JkIHdpbGwgYXBwZWFyIGFmdGVyIHlvdSA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tbG9naW4tdHJpZ2dlciI+bG9nIGluPC9hPiBvciA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tcmVnaXN0ZXItdHJpZ2dlciI+c2lnbiB1cDwvYT5d
Content-Type: application/json

{
   "type": "ssh",
   "domain": "test.com",
   "apiUrl": "11.22.33.44",
   "lang": "en",
   "username": "test.com SSH username",
   "password": "test.com SSH password",
   "uploadDir": "/var/www/test.com/public_html"
}
		
POST /api/requestLogin HTTP/1.1
Host: 
Authorization: Basic W0FQSSBVc2VybmFtZSB3aWxsIGFwcGVhciBhZnRlciB5b3UgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLWxvZ2luLXRyaWdnZXIiPmxvZyBpbjwvYT4gb3IgPGEgaHJlZj0iamF2YXNjcmlwdDp2b2lkKDApIiBjbGFzcz0iYnRuLXJlZ2lzdGVyLXRyaWdnZXIiPnNpZ24gdXA8L2E+XTpbQVBJIFBhc3N3b3JkIHdpbGwgYXBwZWFyIGFmdGVyIHlvdSA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tbG9naW4tdHJpZ2dlciI+bG9nIGluPC9hPiBvciA8YSBocmVmPSJqYXZhc2NyaXB0OnZvaWQoMCkiIGNsYXNzPSJidG4tcmVnaXN0ZXItdHJpZ2dlciI+c2lnbiB1cDwvYT5d
Content-Type: application/json

{
   "type": "local",
   "domain": "test.com",
   "uploadDir": "/var/www/test.com/public_html",
   "lang": "en"
}

Response Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "url": "http://your-builder-domain.com/?login_hash=4asf64df6465"
}

Important: The session URL is active for 30 days per domain. Despite the fact one session URL can be used multiple times per domain during this period it is recommended to generate the fresh URL each time you need to open builder for a customer. Otherwise the session may contain outdated builder configuration and will not match your brand configuration on licenses page.

Response With Error Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
   "error": { "message": "some kind of error message" }
}
We use cookies (and gather certain personal information) to provide you with a better online experience. By visiting our website you accept our terms.