Sites

Sites

The Sites resource is the primary way of publishing and managing any sites, landing pages or any other normal web experiences within the platform.

Site model

Site object

A site object contains the following fields

Attribute	Type	Description
id	integer	unique id of the site
business_id	integer	Reference id to the Business this site is assigned to
business	object	The full Business object expanded
locations	list	List of the assigned Location objects to the site
user_id	integer	Reference id to the User that created this site
deleted	boolean	Field that denotes if the site is disabled or not
base_directory	string	For landing pages, the directory that the page will be published
formatted_domain	string	The hostname/domain where the site is published, including the domain and subdomain (i.e www.example.com)
formatted_url	string	Read-only field that formats the domain, base directory and scheme (i.e. https://www.example.com/)
domain	string	The domain part of the formatted_domain (i.e. example.com)
subdomain	string	The subdomain part of the formatted_domain (i.e. www)
https	boolean	Toggle for enabling SSL for the site
hash	string	Read only and auto-assigned unique hash for the site. Used in preview_url
published	boolean	Toggle for setting the site to a published state. A setting of false (default) will return a 404 if visited on the formatted_url
preview_url	string	Preview URL for this site. Should always be available regardless of published status
title	string	This is the internal name of the site displayed in the site editor user interfaces. Does not show on the published site
custom_fields	object	Custom field values assigned to the site
theme_settings	object	Assigned theme settings values. Support for these values is dependent on the theme
partner_site_id	string	Unique ID reference to partner IDs
language_code	string	The default language (plus specific region) for the site. Similar to the values that browsers send. Examples: en, en-us
theme_id	integer	The assigned Theme object used by the site
disable_analytics_events	list	List of events to disable automatic tracking of
noindex	boolean	Toggle to set the site as non-indexable by search engines
extra_css	string	Extra CSS to add to all the site's pages
footer_code	string	Extra HTML to add to all the site's pages right before the ending </body> tag
header_code	string	Extra HTML to add to all the site's pages right before the ending </head> tag
linklists	list	configuration of the Site's navigation menus
logo	object	fully expanded Logo object
plugins	object	Active site plugins enabled for this site
added	timestamp	Date and time site was created
modified	timestamp	Date and time site was modified
asset_url_prefix	string	Base URL that will be used to prefix static assets. This can be used to enable a CDN for serving these files.
screenshot_thumbnail	string	Link to a thumbnail image preview of the site's homepage
ssl_last_updated	string	Timestamp of when the site's SSL was last updated
www_primary	boolean	Determines if the site should be published prefixed by www. or not
vanity_domain	string	Ability to set a domain, that if pointed, will redirect to this Site

Example object:

{
  "added": "2013-06-19T11:17:13",
  "base_directory": "/",
  "business_id": 432,
  "business": {
    ... fully expanded `Business` object
  },
  "custom_fields": {
    "headline_one": "Example headline one",
    "headline_two": "Example headline two",
    "bullet_points": [
      "Bullet point one",
      "Bullet point two"
    ]
  }
  "deleted": false,
  "disable_analytics_events": ["form-submit"],
  "domain": "yourdomain.com",
  "extra_css": ".body { background-color: red }",
  "formatted_domain": "www.yourdomain.com",
  "formatted_url": "https://www.yourdomain.com/",
  "footer_code": "<script>...</script>",
  "hash": "934dc52",
  "header_code": "<meta .../>",
  "https": true,
  "id": 1234,
  "language_code": "en-us",
  "linklists": [
    ... configuration of the Site's menu
  ],
  "locations": [
    ... list of associated `Location` objects
  ],
  "logo": {
    ... fully expanded `Logo` object
  },
  "modified": "2014-01-28T13:20:13",
  "noindex": false,
  "partner_site_id": "site-12345",
  "plugins": {},
  "preview_url": "http://934dc52.whitelabel.cloudpreview.net/",
  "published": true,
  "resource_uri": "/api/v2/sites/1234/",
  "screenshot_thumbnail": "https://api.urlbox.io/v1/f45f325d-c052-4f54-a839-e3b6fb93bb73/e751570235f0e814d6e94864aa361552bb234fbb/png?url=http%3A%2F%2F934dc52.whitelabel.cloudpreview.net%2F&width=1280&thumb_width=640&height=800",
  "ssl_last_updated": null,
  "subdomain": "www",
  "theme_id": 123,
  "theme_settings": {
    "body_background_color": "#000000",
    "hide_navigation": false
  },
  "title": "Site Title (internal use only)",
  "trace_id": null,
  "user": {
    ... fully expanded `User` object
  },
  "user_id": 248114,
  "www_primary": true,
  "vanity_domain": "vanitydomain.com"
}

Custom fields

Each site that is built on the platform can be assigned custom_fields values that can then be used throughout templates and pages.

This field can contain a structured JSON object with support for nested values.

"custom_fields": {
  "headline_one": "Example headline one",
  "headline_two": "Example headline two",
  "bullet_points": [
    "Bullet point one",
    "Bullet point two"
  ]
}

From this example, the value can be used in templates via either the macro ($custom_headline_one) or via template variable ({{ site.custom_fields.headline_one }}). More examples here.

Create a site

POST /api/v2/sites/

Required fields

Attribute
formatted_domain
theme_id
title

List sites

List all sites including active, deleted, non-published and published

GET /api/v2/sites/

List all active sites

GET /api/v2/sites/?deleted=0

Parameters

Name	Type	Description
added__date	string	Filter for sites created on a particular date in YYYY-MM-DD format
business_id	string	Filter for sites associated with a particular Business
deleted	string	Return sites based on if they are active (0) or deleted/disabled (1)
formatted_domain	string	Searching by domain/subdomain similar to how you pass formatted_domain on Site creation
location_id	string	Filter for sites associated with a particular Location
order_by	string	Set the field to sort the results by. Available order_by includes id (default) and title. You can also sort decending by prefixing the field with a minus sign (i.e. order_by=-id)
partner_site_id	string	Used to lookup/search for sites matching a particular internal id

Response

{
  "meta": {
    "limit": 20,
    "next": "/api/v2/sites/?limit=20&offset=20",
    "offset": 0,
    "previous": null,
    "total_count": 1039
  },
  "objects": [
    {
      "about": "<p>Here is a description of this Site</p>",
      "added": "2013-06-19T11:17:13",
      "base_directory": "/",
      "business_id": 24305,
      "deleted": false,
      "domain": "cloudpreview.net",
      "formatted_domain": "somesite.cloudpreview.net",
      "formatted_url": "http://somesite.cloudpreview.net/",
      "hash": "934dc52",
      "id": 1281131,
      "keywords": "",
      "modified": "2014-01-28T13:20:13",
      "parent_id": null,
      "partner_site_id": null,
      "partner_sub_id": null,
      "published": true,
      "resource_uri": "/api/v2/sites/1281131/",
      "subdomain": "somesite",
      "theme_id": 449,
      "title": "Site Title (internal use only)",
      "type": "default",
      "user_id": 248114,
      "www_primary": false
    },
    {
      "about": "<p>This is Site number two</p>",
      "added": "2013-06-19T11:17:13",
      "base_directory": "/",
      "business_id": 15555,
      "deleted": false,
      "domain": "cloudpreview.net",
      "formatted_domain": "www.somerealdomain.com",
      "formatted_url": "http://www.somerealdomain.com/",
      "hash": "8c7d6s",
      "id": 1281132,
      "keywords": "",
      "modified": "2014-01-28T13:20:13",
      "parent_id": null,
      "partner_site_id": null,
      "partner_sub_id": null,
      "published": true,
      "resource_uri": "/api/v2/sites/1281132/",
      "subdomain": "www",
      "theme_id": 449,
      "title": "Site Title (internal use only)",
      "type": "default",
      "user_id": 248114,
      "www_primary": true
    },
    ...
  ]
}

Get a single site

Fetch the Site detail using the Site.id

GET /api/v2/sites/:id/

Updating a site

PUT /api/v2/sites/:id/

You can PUT a partial or full object to the detail endpoint to update/change values on the Site object. If using a partial object, you must insure that the primary site id is part of the payload.

Disabling / enabling a site

Disabling a site

To disable an active site and clear all cache references to the domain, use the DELETE method on the Site detail endpoint.

DELETE /api/v2/sites/:id/

Enabling a site

To enable a currently disabled site, you will set the param for deleted to False using the Site update endpoint.