How to Export Data from Helpjuice: Methods, API Limits & Portability

How to Export Data from Helpjuice: Methods, API Limits & Portability

Helpjuice gives you four primary ways to get data out: a full backup zip (CSV files plus uploaded media), XLS/CSV exports from the admin dashboard, per-article PDF/DOCX/HTML exports, and the REST API v3. A separate Analytics API handles search and engagement data. Unlike many knowledge base platforms, such as Help Scout or Helpshift, Helpjuice is relatively export-friendly — but none of the UI methods give you a single migration-ready dataset with relational integrity intact.

If you are moving to another platform, you will almost certainly need API v3 combined with the backup zip to get a complete, structured extraction. The API gives you clean JSON with articles linked to categories, authors, and keywords. The backup gives you uploaded media files and multi-category mappings that the API does not reliably expose. This guide covers every extraction method, what each one actually returns, the exact rate limits and pagination constraints, field-level differences between bulk and single-record endpoints, and the gaps that can silently break a migration.

What Data Can You Export from Helpjuice?

Helpjuice's data model centers on Articles (called "Questions" in the legacy API and backup CSVs), Answers (article bodies in HTML), Categories, Users, Groups, Activities, Searches (analytics), and uploaded media. The terminology is a legacy artifact: "Questions" = article metadata, "Answers" = article body content. This distinction matters immediately when parsing backup CSVs or v2 API responses where you will never see the word "article."

Here is what each export method actually gets you:

The critical gap: Uploaded media (images and files embedded in articles) is included in the backup zip but has no dedicated API endpoint. If you use the API alone to extract articles, the body field contains HTML with image URLs pointing to Helpjuice's CDN (static.helpjuice.com). Those URLs work as long as your account is active, but they are not permanent. You must parse them out and download them separately.

Method 1: Backup & Restore (Full Zip Download)

Best for: Complete offline backup, disaster recovery, or migration prep when you want raw data for all objects at once.

The backup is the closest thing Helpjuice has to an "export everything" button. The zip file contains:

• questions.csv — Article metadata (id, codename/slug, name, description, views, created_at, updated_at, is_published, language_id, category_id, joined_tag_names, language_code, next_expiration_on)
• answers.csv — Article body content (id, question_id, user_id, body as HTML)
• categories.csv — All categories (id, parent_id, name)
• categorizations.csv — Article-to-category mapping (supports many-to-many via "Also Display In")
• groups.csv — User groups and permissions
• passes.csv — Permission passes for categories and articles
• uploads.csv — Table of uploaded assets with filenames
• categories/ folder — The actual uploaded image/media files
• account_id — Your account identifier

How to access it:

1. Log in as a Super Administrator or Administrator
2. Navigate to Backup & Restore in the dashboard
3. Download the latest backup

Backup limitations

• CSV format only. No JSON. Article bodies are raw HTML strings inside CSV cells, which means you need to handle CSV escaping carefully — HTML with commas, quotes, and newlines inside cells can break naive parsers. Use a library that handles RFC 4180 CSV correctly (Python's csv module, not a naive split(',') approach).
• Articles are split across two files. You must join questions.csv and answers.csv on question_id to reassemble a complete article.
• No incremental backups. Every backup is a full snapshot.
• Internal/private content is included. Unlike PDF/DOCX exports, the backup does contain internal and private articles.
• answer [] is an array. Helpjuice supports multiple answer records per question (used for versioning and localization). The answers.csv will contain multiple rows for question_id if the article has been through versioning cycles or has language variants. Join on both question_id and the most recent updated_at to get the current content.

Method 2: XLS/CSV Export from Admin Dashboard

Best for: Quick ad-hoc exports for reporting, auditing, or feeding into spreadsheet tools.

From Settings > Export Data, you can export six object types individually: Answers, Questions, Categories, Users, Searches, and Activities — each as XLS or CSV.

Key behavior:

• Exports are emailed to you and also downloadable from the Recent Exports section.
• Only Super Administrators and Administrators can access this.
• Article bodies (Answers) are exported as raw HTML.
• You need to download both Questions and Answers files to get a complete article dataset.

Data dictionary

Questions (Article Metadata):

Answers (Article Bodies):

Method 3: Per-Article and Per-Category PDF, DOCX, HTML

Best for: Sharing formatted documentation externally, archiving individual articles, or content review.

You can export individual articles or entire categories to PDF, DOCX, or HTML from the dashboard. The export is generated server-side and emailed to you.

Why this is not a migration tool:

• Internal sections are stripped. Articles with internal blocks will have those blocks removed from the PDF/DOCX output. If you have mixed-visibility content, these exports are incomplete.
• One category at a time. You cannot select multiple categories for a single export.
• No relational data. No IDs, no metadata, no category mappings, no author information.
• PDF customization is available. You can add a header, logo, custom text, and toggle a table of contents via Settings > Export Settings.

Method 4: Helpjuice REST API v3

Best for: Programmatic extraction of structured data for migration, integration, or sync workflows.

The API v3 is the only method that gives you clean, structured JSON with relational links between articles, categories, users, and groups. It is the right tool for any migration or integration project.

Authentication

All API v3 requests require an API key, passed either as:

• An Authorization HTTP header
• An api_key query parameter

The API key is found at Settings > API Credentials. The "Require token for API" option must be enabled. The key must belong to an Administrator account and effectively grants Super Administrator privileges — keep it server-side, not in frontend code.

# Header-based auth
curl -H "Authorization: YOUR_API_KEY" \
  https://yourcompany.helpjuice.com/api/v3/articles
 
# Query parameter auth
curl https://yourcompany.helpjuice.com/api/v3/articles?api_key=YOUR_API_KEY

Helpjuice also supports an impersonation pattern: use HTTP Basic Auth with a user's email as the username and a blank password to execute requests scoped to that user's access level. This is useful for verifying what internal or private content a given user can see before running a full export. (help.helpjuice.com)

Core Endpoints for Export

The /api/v3/backups endpoint lists existing backups — it does not trigger a new one. Each entry in the response includes a download_url (authenticated, time-limited), a completed_at timestamp, and a status field. The download URL requires the same API key authentication as other endpoints. Use this endpoint to programmatically verify backup freshness before beginning a migration run.

Pagination

All collection endpoints return paginated results. The response includes a meta object:

{
  "meta": {
    "current": 1,
    "limit": 25,
    "total_pages": 4,
    "total_count": 50
  }
}

• Default page size: 25 records
• Maximum page size: 1,000 records (set via ?limit=1000)
• Page navigation: ?page=2&limit=1000

For a complete export, loop through pages until current equals total_pages:

import requests
import time
 
base = "https://yourcompany.helpjuice.com/api/v3/articles"
headers = {"Authorization": "YOUR_API_KEY"}
all_articles = []
page = 1
 
while True:
    resp = requests.get(base, headers=headers, params={"page": page, "limit": 1000})
    
    if resp.status_code == 429:
        # Helpjuice returns 429 when rate limit is exceeded.
        # Retry-After header is not documented; use exponential backoff.
        wait = 2 ** (page % 5)  # cap backoff at ~32 seconds
        print(f"Rate limited. Waiting {wait}s before retry.")
        time.sleep(wait)
        continue
    
    resp.raise_for_status()
    data = resp.json()
    all_articles.extend(data["articles"])
    
    if page >= data["meta"]["total_pages"]:
        break
    
    page += 1
    time.sleep(0.65)  # ~92 requests/min, safely under 100/min limit

Rate Limits

Helpjuice API v3 enforces a rate limit of 100 requests per minute — roughly 1.6 requests per second. When exceeded, the API returns HTTP 429 Too Many Requests. The response body contains an error message; a Retry-After header is not documented in Helpjuice's official API reference, so implement exponential backoff rather than relying on header-driven retry timing.

Rate limit planning by KB size:

Add a 650ms delay between requests (0.65s × 100 = 65s per 100 requests, leaving headroom) to stay safely under the limit without sacrificing throughput.

Bulk vs. Single-Record API Response: Field Comparison

This is the most consequential difference for migration work. The bulk list endpoint (GET /api/v3/articles) and the single-article endpoint (GET /api/v3/articles/:id) return different field sets:

The answer [] array structure explained: Each article has an array of answer records. Multiple entries occur when an article has language variants (each language gets its own answer record) or in some versioning scenarios. For a monolingual KB, most articles will have exactly one entry. For multilingual KBs, filter by the answer's associated language_id to get the correct version.

What the Article JSON Object Looks Like

Here is a representative (truncated) API v3 response for a single article fetch with ?processed=true:

{
  "question": {
    "id": 48291,
    "name": "How to Reset Your Password",
    "description": "Step-by-step guide for resetting account passwords.",
    "codename": "how-to-reset-your-password",
    "views": 1842,
    "accessibility": 1,
    "published": true,
    "created_at": "2024-03-12T09:14:22.000Z",
    "updated_at": "2025-06-01T14:33:07.000Z",
    "url": "https://yourcompany.helpjuice.com/en_US/account/48291-how-to-reset-your-password",
    "keywords": [
      { "id": 112, "name": "password" },
      { "id": 113, "name": "account access" }
    ],
    "answer": [
      {
        "id": 91045,
        "question_id": 48291,
        "user_id": 7,
        "format": "wysiwyg",
        "body": "<p>To reset your password...</p><img src=\"https://static.helpjuice.com/helpjuice_production/uploads/example.png\">",
        "body_txt": "To reset your password...",
        "processed_body": "<p>To reset your password...</p><img src=\"https://static.helpjuice.com/helpjuice_production/uploads/example.png\">",
        "updated_at": "2025-06-01T14:33:07.000Z"
      }
    ]
  }
}

Note: processed_body differs from body only when the article contains embedded article references (Helpjuice's internal block feature). When no embedding is present, both fields are identical. Use the presence of a mismatch between body and processed_body as your detection signal for embedded content.

Filtering Articles

The /api/v3/articles endpoint supports filters useful for incremental or staged exports:

The Analytics API

Helpjuice exposes search and engagement analytics through a separate API surface that follows the same authentication and pagination rules as v3. Key endpoints:

The Analytics API caches results for 1 hour and supports explicit date filters (since and upto in YYYY-MM-DD format). Always pass explicit date ranges — omitting them causes Helpjuice to apply default windows that may not cover your full dataset. Maximum page size is 1,000 records, same as v3.

curl --get -H "Authorization: $HELPJUICE_API_KEY" \
  --data-urlencode "since=2026-08-01" \
  --data-urlencode "upto=2026-08-14" \
  --data-urlencode "limit=1000" \
  "https://yourcompany.helpjuice.com/api/v3/analytics/searches"

Export analytics only if the destination platform can use it — for search-term analysis, content pruning, or redirect planning. Keep the analytics payload separate from your content payload so the migration mapping stays clean.

The Legacy API v2

Helpjuice maintains its older API at /api/ (no version prefix). It exposes four endpoints: /api/questions, /api/answers, /api/categories, and /api/searches. These support .xls, .csv, and .json response formats (append the extension to the URL). Pagination uses ?page=X&limit=Y with a default of 250 records and a maximum of 1,000 per page.

curl "https://yourcompany.helpjuice.com/api/questions.json?api_key=YOUR_KEY&limit=1000&page=1"

Capability comparison — v2 vs. v3:

The only reason to use v2 is if you specifically need XLS output or if legacy scripts already depend on it. For any new migration or integration work, use v3 exclusively.

Handling Multilingual Knowledge Bases

Helpjuice supports 50+ languages and allows articles to be translated. Both API versions support language scoping:

API v3: Add ?filter [language]=es_es (lowercase) to filter articles by language. When fetching a single article with ?kb_language=es_ES, Helpjuice returns the Spanish version if it exists, otherwise falls back to the default language version. Critically, the fallback behavior means you cannot rely on the presence of a response to confirm a translation exists — you must compare the returned language_id or language_code against what you requested.

API v2: Insert the language code into the URL path: /api/en_US/questions.

Migration implications for multilingual KBs:

• Export each language separately with explicit language filters.
• The v3 API does not return a translation_of or source_article_id field — there is no parent-child link between translations in the API response.
• Map translations by matching codename values across language-scoped exports. Articles that are translations of the same source share the same codename.
• When Helpjuice syncs updated content for translation, the entire article is retranslated, not just the changed sections. If you export, modify, and re-import multilingual content during the same migration window, re-trigger translation after content changes are finalized.

(help.helpjuice.com)

The Asset Extraction Problem

The most complex part of a Helpjuice migration is not getting the text out — it is handling embedded assets.

When authors upload images to a Helpjuice article, those images are hosted on Helpjuice's infrastructure. The API returns article bodies containing HTML like this:

<p>To reset your password, click the gear icon:</p>
<img src="https://static.helpjuice.com/helpjuice_production/uploads/your/image.png" alt="Settings Gear">

If you push this HTML directly into a target platform like Freshdesk or Zendesk Guide, the images will render initially. But once your Helpjuice account is deactivated, those CDN URLs die — resulting in broken images across your entire new knowledge base.

The backup zip includes uploaded media in the categories/ folder, which helps. But if you are building your extraction from the API, you must parse the HTML of every article, download the assets, and rewrite the URLs.

Parse and Download

from bs4 import BeautifulSoup
import requests
import os
import time
 
HELPJUICE_DOMAINS = ("static.helpjuice.com", "helpjuice.com")
 
def extract_and_download_assets(html_body, article_id, output_dir="./assets"):
    """
    Parses HTML body, downloads all Helpjuice-hosted assets,
    and returns modified HTML with local file paths as placeholders.
    Replace placeholder paths in a second pass after upload to target platform.
    """
    soup = BeautifulSoup(html_body, 'html.parser')
    os.makedirs(output_dir, exist_ok=True)
    
    # Handle img tags and anchor tags pointing to downloadable files
    for tag, attr in [("img", "src"), ("a", "href"), ("video", "src")]:
        for element in soup.find_all(tag):
            url = element.get(attr)
            if not url or not any(domain in url for domain in HELPJUICE_DOMAINS):
                continue
            try:
                resp = requests.get(url, timeout=30)
                resp.raise_for_status()
                filename = f"{article_id}_{url.split('/')[-1].split('?')[0]}"
                filepath = os.path.join(output_dir, filename)
                with open(filepath, 'wb') as f:
                    f.write(resp.content)
                element[attr] = f"__ASSET_PLACEHOLDER__{filepath}"
                time.sleep(0.1)  # Be a considerate client
            except requests.RequestException as e:
                print(f"Failed to download {url}: {e}")
                # Leave original URL; flag for manual review
    
    return str(soup)

Upload and Rewrite

During the import phase to your new platform:

1. Upload each saved asset to the target platform's storage or an independent CDN.
2. Capture the new URL returned by the target system's upload API.
3. Run a string replacement pass on the HTML body, replacing __ASSET_PLACEHOLDER__./assets/filename with the new URL.
4. Push the rewritten HTML body when creating the article in the target platform.

Resolving Internal Knowledge Base Links

Knowledge base articles frequently reference one another. In Helpjuice, an internal link in the article HTML looks like:

<a href="/articles/12345-how-to-configure-sso">SSO Setup Guide</a>

When you migrate to a new platform, that article receives a completely new ID and URL. If you do not remap these links, users clicking "SSO Setup Guide" in the new system will hit a 404.

The Multi-Pass Strategy

1. Pass 1 (Structure): Create all articles in the target platform as drafts or placeholders. Capture the mapping: helpjuice_article_id → target_article_id and target_url. Store this as a lookup dictionary.
2. Pass 2 (Content Scan): Iterate through all Helpjuice HTML bodies. Use a regex to find href attributes containing /articles/ patterns and extract the numeric ID from the slug format (/articles/12345-slug-text).
3. Pass 3 (Rewrite): For each matched Helpjuice ID, look up the new target_url in your mapping dictionary and replace the href value. Log any IDs without a mapping — these are references to deleted or inaccessible articles.
4. Pass 4 (Update): Push the updated HTML body to the target platform to replace the placeholder content.

import re
 
def rewrite_internal_links(html_body, id_map):
    """
    id_map: dict of {helpjuice_article_id (int): new_target_url (str)}
    """
    def replace_link(match):
        article_id = int(match.group(1))
        new_url = id_map.get(article_id)
        if new_url:
            return f'href="{new_url}"'
        else:
            print(f"Warning: No mapping for Helpjuice article ID {article_id}")
            return match.group(0)  # Leave original if no mapping found
    
    pattern = r'href="/articles/(\d+)[^"]*"'
    return re.sub(pattern, replace_link, html_body)

HTML Formatting and Sanitization

Helpjuice provides a WYSIWYG editor, which means the underlying HTML can contain complex nested <div> structures, inline CSS styles, and custom table formatting.

Many target platforms (like Zendesk Guide or Intercom) have strict HTML sanitization rules that will strip inline style attributes, custom classes, or unsupported tags like <iframe>.

Before pushing Helpjuice HTML into a new system:

• Strip inline styles: Convert inline CSS (e.g., <span style="font-weight: bold;">) to semantic HTML (<strong>). Python's bleach library with a custom css_sanitizer handles this.
• Check iframe whitelists: If your articles contain embedded YouTube or Loom videos via <iframe>, verify the target platform allows iframes from those domains. If not, the video content silently disappears on import.
• Normalize tables: Ensure tables use standard <thead>, <tbody>, <tr>, and <td> tags. Malformed tables from older articles will break target platform parsers. Run through an HTML parser before import to surface structural issues.
• Check for Helpjuice-specific custom components: Some WYSIWYG extensions (callouts, alerts) may render as non-standard HTML. Identify and transform these before import.

Edge Cases That Break Migrations

Internal blocks need processed_body

Helpjuice allows embedding one article inside another. The raw body field stores a placeholder reference (not the embedded content). Only the processed_body field (available via ?processed=true on individual article GETs) renders the embedded content inline. Detection: compare body length to processed_body length — a significant difference indicates embedded content.

Article-to-category mapping is many-to-many

Helpjuice's "Also Display In" feature lets a single article appear in multiple categories. The categorizations.csv in the backup captures all associations. The API v3 GET response for an individual article includes the primary category URL but does not return all associated categories as a structured field. Use the backup CSV as your authoritative source for category mapping — the API alone will silently drop secondary category associations.

Draft vs. published content

The published field is boolean, but Helpjuice allows articles to have published content and pending draft changes simultaneously. The API returns the published version by default. There is no documented API endpoint to retrieve the in-progress draft body when a published version already exists. If draft preservation is part of your migration scope, this requires manual handling or direct Helpjuice support engagement.

Private and internal content scoping

Articles with accessibility set to 0 (internal) or 2 (private) require authentication to retrieve. A Super Admin API key returns all content. User impersonation via HTTP Basic Auth scopes the response to that user's permissions — which may silently exclude private content from your export without any error indication. Validate your export counts against known totals before considering the extraction complete.

Helpjuice enforces rules about what content can live inside public, internal, and private categories. Flattening content without carrying access rules forward risks overexposing internal knowledge in the destination platform. (help.helpjuice.com)

Revision history is not clearly exportable

Helpjuice supports article versions and revisions in the editor, but the standard export paths (backup zip and API) return only the current published state, not the version history. If editorial history is part of your compliance or audit scope, verify this separately with Helpjuice support before assuming the backup covers it. (help.helpjuice.com)

Deleted articles are recoverable for 90 days

Before taking a final snapshot, check the Activities area for recently deleted content. Helpjuice retains deleted articles for up to 90 days and allows restoration. Recover anything needed before starting the export — you cannot go back after account cancellation. (help.helpjuice.com)

Round-trip import constraints

Helpjuice's import documentation specifies .xls format — not .xlsx. Even though Helpjuice exports HTML-rich content and JSON via API, a direct reverse import path does not exist without a transform layer. For complex round-trip scenarios, engage Helpjuice's import team before assuming the format will be accepted. (help.helpjuice.com)

Webhooks for continuous sync

Helpjuice API v3 supports webhooks for real-time event notifications on articles, categories, and users (create, update, delete). Configure them via POST /api/v3/webhooks with a url and event_types payload, and test with POST /api/v3/webhooks/:id/test. Webhook payloads follow the same JSON structure as the corresponding GET endpoint responses. Retry behavior and delivery guarantees are not documented in Helpjuice's official reference — implement idempotent receivers and use updated_at timestamps to detect duplicate deliveries.

Building a Migration-Ready Export: Step by Step

Here is the complete sequence for extracting a Helpjuice knowledge base for migration:

1. Get the right access. You need Super Administrator or account owner access for Backup & Restore and API credentials. Confirm your API key returns the expected total article count before proceeding.

2. Restore deleted content. Check Activities for articles deleted within the last 90 days. Restore anything needed before the snapshot.

3. Download the backup zip. This gives you uploads, categorizations, groups, and permissions in one shot. Store an untouched copy as your rollback point. Note the completed_at timestamp.

4. Export all articles via API v3 with ?limit=1000 pagination. Validate meta.total_count matches your known article count.

5. Detect and fetch articles with embedded content. Compare body length vs processed_body length on a sample. For any article where they differ, fetch GET /api/v3/articles/:id?processed=true to get the expanded content.

6. Export categories, users, and groups via API v3. The category response includes published_questions and draft_questions arrays. Map user_id to name and email for author attribution.

7. Parse and download all media assets. Scan all body HTML fields for src and href attributes pointing to static.helpjuice.com. Deduplicate URLs before downloading. Rewrite to placeholder tokens for the second-pass URL update.

8. Cross-reference categorizations.csv from the backup to identify articles in multiple categories. This data is not reliably available via API alone.

9. Map and rewrite internal links. Use the multi-pass strategy above. Log any unmapped IDs for manual review.

10. Sanitize HTML for the target platform's requirements — strip inline styles, normalize tables, verify iframe compatibility, transform custom components.

11. Export analytics if you need search intent data for content gap analysis or redirect planning. Keep this payload separate from content.

12. Validate in the target. Spot-check article HTML, slugs, access levels, category hierarchy, translations, and attachments. Confirm image rendering and internal link resolution before cutover.

API v3 vs. Backup vs. Dashboard Export: Which to Use When

Summary: What Helpjuice Exports Well and Where the Gaps Are

Helpjuice's export surface is better than many knowledge base platforms — you can get meaningful structured data out through multiple channels without severe vendor lock-in. The documented rate limit (100 req/min), clean JSON responses, date-range filters, and backup zip together give you a complete extraction path.

The real friction points are:

• Media assets have no API endpoint — CDN URLs must be parsed and downloaded separately.
• Multi-category mappings are only complete in the backup's categorizations.csv — not in API responses.
• processed_body is only available on single-article GETs with ?processed=true, requiring N additional requests beyond the bulk list.
• Draft content is not accessible when a published version exists.
• Translation relationships (parent-to-translation linking) must be inferred from matching codenames across language-scoped exports.
• Revision history is not part of any standard export path.

For a KB with hundreds of articles, basic extraction is straightforward. The engineering effort scales with embedded content, multilingual variants, complex category hierarchies, and the strictness of the target platform's HTML sanitization. The text extraction is the easy part — the field mapping, asset re-hosting, link rewriting, and access-level translation to the destination platform's permission model is where migrations fail.

For broader context on migration planning, see our knowledge base migration checklist and our overview of help desk migration tools and services. If you are considering running the entire migration through spreadsheets, read Using CSVs for SaaS Data Migrations first.