> For the complete documentation index, see [llms.txt](https://api-docs.devhub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.devhub.com/core-resources/sites.md). # 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)](/advanced/language-codes.md) 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](/core-resources/sites.md#updating-a-site). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-docs.devhub.com/core-resources/sites.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.