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.

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.

Call API URL (on-premises): http://your-builder-domain.com/api/requestLogin
Call API URL (cloud): https://site.pro/api/requestLogin
Authorisation: HTTP Basic
Username: [API Username from brand]
Password: [API Password from brand]
Method: POST
Content Type: application/json
Return Content Type: 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 type – "external"
String type – "internal"
String type – "http"
String type – "ssh"
String type – "local"
String domain – 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 username – Client FTP connection username.
String username – Client SSH connection username.
String password – Client FTP connection password.
String password – Client SSH connection password (not needed if using SSH keys).
String uploadDir – Client document root directory, relative to FTP account root folder (e.g. "/public_html").
String uploadDir – Full path to website document root.
String uploadDir – Full path to website document root.
String apiUrl – IP address of client's server.
String apiUrl – Your API endpoint URL.
String apiUrl – Your API endpoint URL (it must include website identifier on your hosting).
Number resellerClientAccountId – Website/User ID on your end. It will be passed during your API endpoint call as one of parameters during site publication.
String username – HTTP Basic Authorisation username to call API endpoint URL.
String password – HTTP Basic Authorisation password to call API endpoint URL.

Important: 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.

Important: If you want to use SSH keys instead of the password, then find public key in your on-premises builder installation (path to the file: [builder]/src/sign/public_key.txt) and add its contents on target server into the file ".ssh/authorized_keys" of an appropriate user.

Optional:

String lang – Language 2 letter code (ex. "en", "ru", ...) to open builder in.
String hostingPlan – Hosting plan identifier, will be used for builder feature limitations by plan.
String baseDomain – 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 customLogo – URL to image to use as builder logo (if not set will be taken from brand).
String customLogoMobile – URL to image to use as builder logo on mobile devices (if not set will be taken from brand).
String customFavicon – URL to image/icon to use as builder favicon (if not set will be taken from brand).
String customTitle – Title to use for builder (if not set will be taken from brand).
Boolean customLocked – Do not allow users to remove builder logo from their websites (if not set will be taken from brand).
String customLockedUrl – URL to place on builder logo in users website.
String extReferenceId – Custom identifier accessible in builder plugins.
String templatePath – 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 openPageId – Page ID to open in builder. (on-premises only since v3.7.345)
String createFrom – Required only when using remote API endpoint of User registration from Public Demo builder
Boolean more – If set to true response will contain additional two properties: loginHash and builderApiUrl
Boolean migrateHide – If set to true then migration to v4 builder dialog will be suppressed

Return Object Properties:

String url – Url to redirect client to (only on success)
String loginHash – Hash that may be used with website controlling API calls (only on success when request property more is set to true)
String builderApiUrl – 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 – Error description object (only on error). Error object structure:
- String message – 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 URL: API endpoint URL
Authorisation: HTTP Basic
Username: Value of parameter "username" passed to builder API call
Password: Value of parameter "password" passed to builder API call
Method: POST/GET
Content Type: application/x-www-form-urlencoded
Content Type: application/x-www-form-urlencoded, application/octet-stream
Return Content Type: application/json
Return Content Type: 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 zip – URL to zip file containing website generated files. This zip must be downloaded and extracted to client's hosting.
Number account_id – Value of parameter "resellerClientAccountId" passed to builder API.
String domain – Value of parameter "domain" passed to builder API.
String hostingplan – Value of parameter "hostingPlan" passed to builder API (if was set).

API endpoint return result (JSON format):

Object result – (required if error is not returned) Result description object with structure:
- String id – (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 error – (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 – Result description object with structure:
- String status – (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 output – (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 URL: API endpoint URL + / [file path]
Authorisation: HTTP Basic
Username: Value of parameter "username" passed to builder API call
Password: Value of parameter "password" passed to builder API call
Method: POST
Content Type: application/octet-stream

Response:

200 – OK.
403 – Access denied.

Delete file

Should delete the specified file on the server.

Request:

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

Response:

200 – OK.
403 – Access denied.

Create directory

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

Request:

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

Response:

200 – OK.
403 – Access denied.

Get directory files listing

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

Request:

API URL: API endpoint URL + / [directory path] ?list=1
Authorisation: HTTP Basic
Username: Value of parameter "username" passed to builder API call
Password: Value of parameter "password" passed to builder API call
Method: GET
Return Content Type: 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: your-builder-domain.com
Authorization: Basic W0FQSSBVc2VybmFtZSBmcm9tIGJyYW5kXTpbQVBJIFBhc3N3b3JkIGZyb20gYnJhbmRd
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: your-builder-domain.com
Authorization: Basic W0FQSSBVc2VybmFtZSBmcm9tIGJyYW5kXTpbQVBJIFBhc3N3b3JkIGZyb20gYnJhbmRd
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: your-builder-domain.com
Authorization: Basic W0FQSSBVc2VybmFtZSBmcm9tIGJyYW5kXTpbQVBJIFBhc3N3b3JkIGZyb20gYnJhbmRd
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: your-builder-domain.com
Authorization: Basic W0FQSSBVc2VybmFtZSBmcm9tIGJyYW5kXTpbQVBJIFBhc3N3b3JkIGZyb20gYnJhbmRd
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: your-builder-domain.com
Authorization: Basic W0FQSSBVc2VybmFtZSBmcm9tIGJyYW5kXTpbQVBJIFBhc3N3b3JkIGZyb20gYnJhbmRd
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" }
}