Developers

# Sites

This endpoint let you manage all sites you have access to.

# The site object

  • id integer

    The system-generated ID of the site.

  • account_id integer

    The system-generated ID of the conversation account.

  • mailbox_id integer

    The ID of the mailbox to use for messages sent through the site's contact form.

  • name string

    The name of the site.

  • host string

    The host of the site. If the site doesn't have a custom domain, the host will be the app's host with the site's subdomain. If the site is using a custom domain, host will be the custom domain.

  • path string

    The path used for path-based routing.

  • subdomain string

    The subdomain of the site.

  • subdomain_host string

    The site's host for the subdomain value. For example, if subdomain is docs and the software is installed on desk.mydesk.com, the subdomain host is docs.mydesk.com.

  • custom_domain string

    The custom domain of the site (e.g., www.myknowledgebase.com).

  • url string

    The URL of the site. This value can be used to generate anchor tags.

  • html_head string

    Custom content to be added to the <head></head> section on the site. Things like stylesheets, fonts, javascript, meta tags, etc.

  • visibility enum: public, private

    The visibility of the site. When public (default), the site is accessible publicly. When private, the site is only accessible by logged-in agents.

  • created_at string

    The timestamp when the user was created.

  • updated_at string

    The timestamp when the user was last updated.

# The site object

{
  "id": 1,
  "account_id": 1,
  "mailbox_id": null,
  "name": "My site",
  "host": "docs.mycustomdomain.com",
  "path": "my-site",
  "subdomain": "mysite",
  "subdomain_host": "mysite.yourdomain.com",
  "custom_domain": "docs.mycustomdomain.com",
  "url": "https://docs.mycustomdomain.com",
  "html_head": null,
  "visibility": "public"
}

# Create a site

  • account_id integer required

    The account id where the site belongs to.

  • mailbox_id integer optional

    The ID of the mailbox to use for messages sent through the site's contact form.

  • name string required

    The name of the site.

  • path string optional

    The path of the site. If no value is provided, a random string will be used.

  • subdomain string optional

    The subdomain of the site.

  • custom_domain string optional

    The custom domain of the site (e.g., www.myknowledgebase.com).

  • html_head string optional

    Custom content to be added to the <head></head> section on the site. Things like stylesheets, fonts, javascript, meta tags, etc.

  • visibility enum: public, private optional

    Use public if you want your customers to navigate the site, use private otherwise. If no visibility is passed, public is used.

# Sample request

curl https://www.yourdomain.com/api/v1/sites \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d name="My site" \
  -d subdomain="mysite" \
  -d custom_domain="docs.mycustomdomain.com" \
  -d account_id=1 \ 
  -d mailbox_id=1

# Sample successful response

{
  "data": {
    "id": 1,
    "account_id": 1,
    "mailbox_id": 1,
    "name": "My site",
    "host": "docs.mycustomdomain.com",
    "path": "...",
    "subdomain": "mysite",
    "subdomain_host": "mysite.yourdomain.com",
    "custom_domain": "docs.mycustomdomain.com",
    "url": "https://docs.mycustomdomain.com",
    "html_head": null,
    "visibility": "public"
  }
}

# Retrieve a site

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \ 
  -G

# Sample successful response

{
  "data": {
    "id": 1,
    "account_id": 1,
    "mailbox_id": 1,
    "name": "My site",
    "host": "docs.mycustomdomain.com",
    "path": "...",
    "subdomain": "mysite",
    "subdomain_host": "mysite.yourdomain.com",
    "custom_domain": "docs.mycustomdomain.com",
    "url": "https://docs.mycustomdomain.com",
    "html_head": null,
    "visibility": "public"
  }
}

# Update a site

  • account_id integer required

    The account id where the site belongs to.

  • mailbox_id integer optional

    The ID of the mailbox to use for messages sent through the site's contact form.

  • name string required

    The name of the site.

  • path string optional

    The path of the site.

  • subdomain string optional

    The subdomain of the site.

  • custom_domain string optional

    The custom domain of the site (e.g., www.myknowledgebase.com).

  • html_head string optional

    Custom content to be added to the <head></head> section on the site. Things like stylesheets, fonts, javascript, meta tags, etc.

  • visibility enum: public, private optional

    Use public if you want your customers to navigate the site, use private otherwise.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1 \
  --request PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d name="My docs site" \
  -d subdomain="mysite" \
  -d custom_domain="docs.mycustomdomain.com" \
  -d account_id=1 \
  -d mailbox_id=2

# Sample successful response

{
  "data": {
    "id": 1,
    "account_id": 1,
    "mailbox_id": 2,
    "name": "My docs Site",
    "host": "docs.mycustomdomain.com",
    "path": "...",
    "subdomain": "mysite",
    "subdomain_host": "mysite.yourdomain.com",
    "custom_domain": "docs.mycustomdomain.com",
    "url": "https://docs.mycustomdomain.com",
    "html_head": null,
    "visibility": "public"
  }
}

# Delete a site

curl https://www.yourdomain.com/api/v1/sites/1 \
  --request DELETE
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>"

If successful, the above request will return an empty response with 204 HTTP status code.

← Site collections →