Developers

# Site themes

These endpoints will let you manage your site's installed themes. A theme is simply a set of files that provides the structure, look, and feel of your knowledge base sites. Each site may have their own set of themes.

# The theme object

  • id integer

    The system-generated ID of the theme

  • name string

    The name of the theme.

  • is_active boolean

    Whether the theme is active (i.e., whether it is the site's current theme).

  • preview_url string

    [DEPRECATED] A unique URL preview.

  • iframe_preview_url string

    [DEPRECATED] A unique URL preview designed to be used for iframes.

  • update_available boolean

    Whether an update is available for a first-party theme.

  • created_at string

    The timestamp when the theme was created.

  • updated_at string

    The timestamp when the theme was last updated.

# The theme object

{
  "id": 1,
  "name": "My first theme",
  "is_active": true,
  "preview_url": "https://...",
  "iframe_preview_url": "https://...",
  "update_available": false,
  "created_at": "2019-06-01T16:12:25+00:00",
  "updated_at": "2019-06-01T16:12:25+00:00"
}

# Retrieve a theme

# Sample request

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

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "My first theme",
    "is_active": true,
    "preview_url": "https://...",
    "iframe_preview_url": "https://...",
    "update_available": false,
    "created_at": "2019-06-01T16:12:25+00:00",
    "updated_at": "2019-06-01T16:12:25+00:00"
  }
}

# Create a theme

This endpoint lets you easily create themes with a default theme structure, layout, and design, so you do not have to start from scratch when customizing your site's look and feel.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/themes \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d name="My custom theme"

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "My custom theme",
    "is_active": true,
    "preview_url": "https://...",
    "iframe_preview_url": "https://...",
    "update_available": false,
    "created_at": "2019-06-01T16:12:25+00:00",
    "updated_at": "2019-06-01T16:12:25+00:00"
  }
}

# Delete a theme

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/themes/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.

# List all themes

# Sample request

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

# Sample successful response

{
  "data": [
    {
      "id": 1,
      "name": "My first theme",
      "is_active": true,
      "preview_url": "https://...",
      "iframe_preview_url": "https://...",
      "update_available": false,
      "created_at": "2019-06-01T16:12:25+00:00",
      "updated_at": "2019-06-01T16:12:25+00:00"
    },
    {...}
  ]
}

# Apply a pending update to a theme

Updates are released periodically, each update may contain bug fixes and minor enhancements to the overall look and feel of your knowledge base site. Updates are only released for first-party themes; themes that you have uploaded will not receive updates, even when those themes are based on first-party themes.

An update will override any custom change made to the theme's code. If you made changes to a first-party theme (by using Theme Kit, for example), keep in mind that updating your theme will override all custom changes.

# Sample request

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

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "My first theme",
    "is_active": true,
    "preview_url": "https://...",
    "iframe_preview_url": "https://...",
    "update_available": false,
    "created_at": "2019-06-01T16:12:25+00:00",
    "updated_at": "2019-06-01T16:12:25+00:00"
  }
}

# Upload a theme

  • zip file required

    The theme's zip file to be uploaded. 30MB max.

# Sample request

curl https://www.yourdomain.com/api/v1/sites/1/themes/upload \
  --request POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -F "zip=@/path/to/ModernTheme.zip"

# Sample successful response

{
  "data": {
    "id": 1,
    "name": "ModernTheme",
    "is_active": false,
    "preview_url": "https://...",
    "iframe_preview_url": "https://...",
    "update_available": false,
    "created_at": "2019-06-01T16:12:25+00:00",
    "updated_at": "2019-06-01T16:12:25+00:00"
  }
}

← Site theme files →