Site.pro
  • Website Builder
    • Website Builder
    • Online Stores
    • Templates
    • Domains
    • Plugins
    • Languages
    • FAQ
    • Affiliate program
    • Examples
    • "For Web Design"
  • Prices
  • Website Import
  • For Resellers
    • White Label
    • Prices
    • Panels
    • How it Works
    • Free Websites
    • Marketing Kit
    • Mass Import
    • Our Partners
    • Free Website Builder
    • Documentation
    • "Shared Hosting Tips"
    • "Domainity"
    • FAQ
  • Contact Sales
  • faceLog In
    Sign In with Facebook Sign In with Google
    or
    Remind password
    A new password will be sent to the specified e-mail address.
    Return to login form
  • inputRegister
    Sign Up with Facebook
    Sign Up with Google
    or
  • $
    • USD — $
    • EUR — €
    • GBP — £
    • BRL — R$
    • PLN — zł
    • INR — ₹
    • TRY — TL
    • AUD — A$
    • CAD — C$
    • CZK — Kč
    • DKK — kr
    • HKD — HK$
    • HUF — Ft
    • ILS — ₪
    • JPY — 円
    • MXN — Mex$
    • NOK — kr
    • NZD — NZ$
    • PHP — ₱
    • RUB — ₽
    • SGD — S$
    • SEK — kr
    • CHF — Fr
    • TWD — NT$
    • THB — ฿
    • CNY — ¥
    • RSD — din
    • BGN — лв.
    • RON — Lei
    • HRK — kn
    • ZAR — R
    • BYN — p.
    • UAH — ₴
    • KZT — ₸
    • CLP — CH$
  • English
    • العربية
    • Azərbaycan
    • Bahasa Indonesia
    • Bahasa Malaysia
    • Беларуская
    • Български
    • Bosanski
    • Castellano
    • Čeština
    • Dansk
    • Deutsch
    • Eesti
    • Ελληνικά
    • English
    • Español
    • 繁體
    • فارسی
    • Français
    • Հայերեն
    • हिन्दी
    • Hrvatski
    • Italiano
    • עברית
    • 简体
    • ქართული
    • Қазақ
    • Latviešu
    • Lietuvių
    • Magyar
    • Nederlands
    • 日本語
    • Norsk
    • O'zbek
    • ภาษาไทย
    • ភាសាខ្មែរ
    • Polski
    • Português (BR)
    • Română
    • Русский
    • Schweizerdeutsch
    • Slovenčina
    • Slovenščina
    • Srpski
    • Suomi
    • Svenska
    • Tiếng Việt
    • Türkçe
    • Украї́нська
    • Wikang Tagalog
    • And additional 2 languages inside Site.pro website builder
  • Website Builder
    • Website BuilderEverybody can easily make a website, landing page or e-commerce.
    • Online StoresSell your goods or services anywhere on the website
    • Templates200+ Awesome Templates. Responsive Design
    • DomainsBuy domain. Connect Your Domain. Transfer Domain.
    • Plugins
    • Languages
    • FAQ
    • Affiliate program
    • Examples
    • "For Web Design"
  • Prices
  • Website Import
  • For ResellersWhite Label
    • White LabelThe most popular white label tool is ideal for reselling
    • PricesStart reselling. Pay for live websites. Free Websites
    • PanelsOne product for all platforms. Download plugin for your panel
    • How it WorksCloud or On-Premises. Recommendations for Builder Server
    • Free WebsitesUnlimited Quantity of Free Websites
    • Marketing KitUse White Label Marketing Kit To Increase Your Sales
    • Mass Import
    • Our Partners
    • Free Website Builder
    • Documentation
    • "Shared Hosting Tips"
    • "Domainity"
    • FAQ
  • Contact Sales
Builder installation / update
  • Server Requirements
  • Installation
  • CRON
  • Update
  • Migration to version v4
  • Extra configuration
  • Manual update
  • Changing PHP version
  • Support
Plugin installation
  • Hosting Panel
    • cPanel
    • DirectAdmin
    • Plesk
    • Sentora/ZPanel
    • ISPmanager
    • InterWorx
    • Vesta
    • Hestia
    • Hosting Controller
    • CentOS Web Panel
    • Custom hosting (API)
  • Billing Panel
    • WHMCS
    • Custom billing (API)
API documentation
  • Builder
    • Create session (SSO)
    • Remove existing session
    • Create website backup
    • Restore website backup
  • Templates
    • List template categories
    • List templates
    • Get page types available in templates
  • Import
    • Import website
    • Get import status
    • Check if imported website is owned by user
  • Websites
    • Create website
    • Modify website
    • Rename website
    • Publish website
    • Edit website pages
    • Edit website settings
    • Enable/disable Auto Layout
    • Delete website
    • Get website template
    • Get website pages
    • Get website variables
    • Get website settings
    • Add pages to website
    • Duplicate pages in website
    • Remove pages from website
  • Website Blocks
    • Create empty website
    • Modify website
    • Inspect website
    • Add empty page
    • Modify page
    • Remove page
    • Inspect page
    • Inspect composition
    • Modification descriptor structure by element type
    • Add blocks from compositions
    • Remove blocks
    • Move blocks
    • Modify blocks
    • Inspect block
  • Licenses
    • Get list of published websites
    • Get statistics of publications/openings
    • Block/unblock published website
    • Controlling IP list
  • Integration with your system
    • Allow/disallow domain in builder
    • Check if domains are allowed in builder
Add-ons documentation
  • For Website
    • Public demo URL
    • User registration from public demo
    • Website import
  • For Builder
    • Adding custom templates
    • Adding custom builder plugins
    • Scripts
For developers
  • Programming reference
  • Directory structure
  • Meta information (main.json)
  • Frontend logic (main.js)
  • Element template (main.html)
  • Backend logic (main.php)
  • Plugin testing
  • Custom element plugin
  • E-commerce plugin
  • Overriding UI
  • Other examples
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.

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.

http://your-builder-domain.com/api/requestLogin
https://site.pro/api/requestLogin
HTTP Basic
[API Username from brand]
[API Password from brand]
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.

  • external
  • internal
  • http
  • ssh
  • local
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.

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 – Language 2 letter code (ex. "en", "ru", ...) to open builder in.
  • String – Hosting plan identifier, will be used for builder feature limitations by plan.
  • 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/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

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: 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" }
}
	
© Site.pro Website Builder. United States, Washington. Terms of Service