Themes

The Themes API lets you manage Guide themes and integrate more complex theme development workflows with Guide.

The API consists of themes and jobs. A theme resource represents a Guide theme. Jobs are used for asynchronous operations.

If you're using multiple brands, send requests to the account domain, not the brand domain.

If you're using OAuth2 authentication, set the required scopes to themes:read or themes:write to perform read operations or all operations, respectively.

JSON Format for Themes

Themes are represented by JSON objects with the following properties:

Name Type Comment
id string Automatically assigned when the theme is created
name string The name of the theme
version string The version number of the theme. Specified in the theme manifest
author string The author of the theme. Specified in the theme manifest
live boolean Whether or not the theme is currently published in Help Center
created_at timestamp The time at which the theme was created
updated_at timestamp The time at which the theme was last updated
brand_id string The brand id of the theme
Example
{
  "id": "asdf123-asdf",
  "name": "Copenhagen",
  "author": "Zendesk",
  "version": "1.7.5",
  "live": true,
  "created_at": "2012-04-04T09:14:57Z",
  "updated_at": "2012-04-04T09:14:57Z"
}

List Themes

GET /api/v2/guide/theming/themes

GET /api/v2/guide/theming/themes?brand_id={brand_id}

Allowed For
  • Guide managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/themes?brand_id={brand_id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "themes": [
    {
      "id":      "asdf123-asdf",
      "name":    "Copenhagen",
      "author":  "Zendesk",
      ...
    },
    ...
  ]
}

Show Theme

GET /api/v2/guide/theming/themes/{id}

Allowed For
  • Guide managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/themes/{id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "theme": {
    "id":      "asdf123-asdf",
    "name":    "Copenhagen",
    "author":  "Zendesk",
    ...
  }
}

Delete Theme

DELETE /api/v2/guide/theming/themes/{id}

Allowed For
  • Guide managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/themes/{id} \
  -v -u {email_address}:{password} -X DELETE
Example Response
Status: 204 No Content

Publish Theme

POST /api/v2/guide/theming/themes/{id}/publish

Allowed For
  • Guide managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/themes/{id}/publish \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 200 OK

{
  "theme": {
    "id":      "asdf123-asdf",
    "name":    "Copenhagen",
    "author":  "Zendesk",
    "live":    true
    ...
  }
}

JSON Format for Jobs

Name Type Comment
status string The current status of the job. Possible values: "pending", "completed" or "failed"
errors array An array of errors if the job failed. Returns null if the job is pending or successful
data object Job-specific data provided on job creation

The errors key may contain an array of error objects. The format of an error object is as follows:

Name Type Comment
title string The error message
code string A unique identifier for the error. List of possible codes
meta object An object with further error information
Example
{
  "status": "pending",
  "errors": null,
  "data": null
}

Show Job

GET /api/v2/guide/theming/jobs/{id}

Allowed For
  • Guide managers
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/jobs/{id} \
  -v -u {email_address}:{password}
Example Response
Status: 200 OK

{
  "job": {
    "status": "failed",
    "errors": [
      {
        "title": "Theme not found",
        "code": "ThemeNotFound",
        "meta": { }
      }
    ]
  }
}

Create Theme Import Job

POST /api/v2/guide/theming/jobs/themes/imports

The endpoint does not receive the ZIP file itself. See Theme Import Workflow for more information.

This job's data object has the following format:

Name Type Comment
theme_id string Automatically assigned when the job is created
upload.url string One-time URL for the storage location
upload.parameters object Parameters to be used when posting the ZIP file to the upload url

Note: The upload parameters should be considered unstable and provided as-is without modification.

Allowed For
  • Guide managers
Request Body Format
Name Type Comment
job.attributes.brand_id string The id of the brand where the theme should be imported to
job.attributes.format enum Valid enums ["zip"]
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/jobs/themes/imports \
  -d '{ "job": { "attributes": { "brand_id": "brand_id", "format":"zip" } } }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202 Accepted

{
  "job": {
    "id": "a66e7bde543c6b6d018f0e07a654feaf",
    "status": "pending",
    "errors": null,
    "data": {
      "theme_id": "asdf123-asdf",
      "upload": {
        "url": "storage.zdassets.com/storage-location",
        "parameters": { ... }
      }
    }
  }
}
Theme Import Workflow

To import a theme:

  1. Create a theme import job with the Create Theme Import Job endpoint.

  2. Upload the file to the storage location specified in the upload object. Upload the file by sending a POST request to the specified upload url. Don't specify any authentication headers. The POST request's Content-Type must be multipart/form-data and each parameter in the parameters object must be provided as a form field in addition to a file field containing the ZIP file to be uploaded.

  3. Poll the job status with the Show Job endpoint to know when the theme is available for use. When the status is "completed", the theme with theme_id is available for use. Avoid polling too frequently to prevent being rate limited. Example: Poll every 5 seconds.

The following is a simplified example without error handing using Ruby.

require 'faraday'
require 'faraday_middleware'

# brand_id =
# subdomain =
# file_path =
# email =
# password =

# Step 1

zendesk_connection = Faraday.new do |faraday|
 faraday.basic_auth(email, password)
 faraday.request :json
 faraday.response :json, content_type: /json/
 faraday.adapter :net_http
end

job_response = zendesk_connection.post("https://#{subdomain}.zendesk.com/api/v2/guide/theming/jobs/themes/imports", { {"job" => { "attributes" => { "brand_id" => brand_id, "format"=> "zip" }}})

job_id = job_response.body['job']['id']
storage_url = job_response.body['job']['data']['upload']['url']
storage_parameters = job_response.body['job']['data']['upload']['parameters']

# Step 2

storage_connection = Faraday.new do |faraday|
 faraday.request :multipart
 faraday.request :url_encoded
 faraday.adapter :net_http
end

storage_body = storage_parameters.merge(file: Faraday::UploadIO.new(file_path, 'application/zip'))
storage_connection.post(storage_url, storage_body)

10.times do
 job_status_response = zendesk_connection.get("https://#{subdomain}.zendesk.com/api/v2/guide/theming/jobs/#{job_id}")
 puts job_status_response.body
 break unless job_status_response.body['job']['status'] == 'pending'
 sleep(5)
end

Create Theme Update Job

POST /api/v2/guide/theming/jobs/themes/updates

The endpoint does not receive the ZIP file itself. See Theme Update Workflow for more information.

This job's data object has the following format:

Name Type Comment
upload.url string One-time URL for the storage location
upload.parameters object Parameters to be used when posting the ZIP file to the upload url

Note: The upload parameters should be considered unstable and provided as-is without modification.

Allowed For
  • Guide managers
Request Body Format
Name Type Comment
job.attributes.theme_id string Id of the theme to export
job.attributes.replace_settings boolean Whether or not to replace the current theme settings
job.attributes.format enum Valid enums ["zip"]
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/jobs/themes/updates \
  -d '{"job": { "attributes": { "theme_id": "theme_id", "replace_settings": true, "format":"zip" } } }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202 Accepted

{
  "job": {
    "id": "a66e7bde543c6b6d018f0e07a654feaf",
    "status": "pending",
    "errors": null,
    "data": {
      "upload": {
        "url": "storage.zdassets.com/storage-location",
        "parameters": { ... }
      }
    }
  }
}
Theme Update Workflow

To update a theme:

  1. Create an theme update job with the Create Theme Update Job endpoint.

  2. Upload the file to the storage location specified in the upload object. Upload the file by sending a POST request to the specified upload url. Don't specify any authentication headers. The POST request's Content-Type must be multipart/form-data and each parameter in the parameters object must be provided as a form field in addition to a file field containing the ZIP file to be uploaded.

  3. Poll the job status with the Show Job endpoint to know when the theme has been updated. When the status is "completed", the theme has been updated to the uploaded version. Avoid polling too frequently to prevent being rate limited. Example: Poll every 5 seconds.

Create Theme Export Job

POST /api/v2/guide/theming/jobs/themes/exports

The endpoint does not deliver the ZIP file itself. See Theme Export Workflow for more information.

This job's data object has the following format:

Name Type Comment
download.url string Where the theme can be downloaded after the job is completed
Allowed For
  • Guide managers
Request Body Format
Name Type Comment
job.attributes.theme_id string Id of the theme to export
job.attributes.format enum Valid enums ["zip"]
Using curl
curl https://{subdomain}.zendesk.com/api/v2/guide/theming/jobs/themes/exports \
  -d '{ "job": { "attributes": { "theme_id": "theme_id", "format":"zip" } } }' \
  -H "Content-Type: application/json" \
  -v -u {email_address}:{password} -X POST
Example Response
Status: 202 Accepted

{
  "job": {
    "id": "a66e7bde543c6b6d018f0e07a654feaf",
    "status": "pending",
    "errors": null,
    "data": {
      "download": {
        "url": "storage.zdassets.com/storage-location"
      }
    }
  }
}
Theme Export Workflow

To export a theme:

  1. Create an theme export job with the Create Theme Export Job endpoint.

  2. Poll the job status with the Show Job endpoint until the job is no longer "pending".

  3. When the job status is "completed", download the theme using the url from the download object.

Errors

Example Error Response
Status: 404 Not Found

{
  "errors": [
    {
      "title": "Theme not found",
      "code": "ThemeNotFound",
      "status": "404",
      "meta": {
        "id": "theme_id"
       }
    }
  ]
}
Status: 400 Bad Request

{
  "errors": [
    {
      "title": "The provided brand is not valid",
      "code": "InvalidBrand",
      "status": "400",
      "meta": { ... }
    }
  ]
}
Generic Error codes
Http status Code Comment
401 InvalidOAuthScopes The oauth scope provided does not match the required scope
400 UnavailableFeatures The theme is attempting to use features not available in the current Guide plan
400 InvalidBrand Incorrect brand id
Themes Error Codes
Http status Code Comment
404 ThemeNotFound The provided theme id is non-existent
400 LiveThemeDeleted A brand's live theme cannot be deleted
Job Error Codes
Http status Code Comment
404 JobNotFound The provided job id is non-existent
400 TooManyThemes Maximum number of allowed themes reached
400 NonUpdatableTheme Attempting to update a non api theme
Failed Job Error Codes
Code Comment
TooManyThemes Maximum number of allowed themes reached
NameTooLong The theme name is longer than allowed
FileNotSupported The file is not supported, wrong extension, dir etc.
FileTooBig An added file is bigger than the allowed
ThemeTooBig The theme is above the maximum size
FileNameTooLong The file name is longer than allowed
FileNotFound A required file cannot be found
FileLimitReached The maximum number of files have been reached
FileDeletionInProgress Attempting to change a file that is marked for deletion
InvalidTemplates Templates have syntax errors
InvalidSetting Setting is not valid
TooManySettings More than the allowed amount of settings
InvalidManifest The manifest is not valid
UnsupportedLocale The locale is not supported
InvalidTranslationFile The translation file is not valid
InvalidThemeVersion The theme version is not valid
NonUpdatableTheme Theme cannot be updated