# 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)](https://api-docs.devhub.com/advanced/language-codes) 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 `` tag | | header\_code | string | Extra HTML to add to all the site's pages right before the ending `` 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: ```javascript { "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": "", "hash": "934dc52", "header_code": "", "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. ```javascript "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](https://docs.devhub.com/themes-and-custom-templates/using-custom-fields). ## 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 ```javascript { "meta": { "limit": 20, "next": "/api/v2/sites/?limit=20&offset=20", "offset": 0, "previous": null, "total_count": 1039 }, "objects": [ { "about": "

Here is a description of this Site

", "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": "

This is Site number two

", "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](#updating-a-site).