API Documentation — HelpdeskHero

Contents

Quick Start

Create a category and article in 3 steps

const API_KEY = "hdh_your_api_key";
const BASE_URL = "https://helpdeskhero.app/api/v1";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

// 1. Create a category
const catRes = await fetch(`${BASE_URL}/categories`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Getting Started",
    description: "Help users get set up",
  }),
});
const { data: category } = await catRes.json();

// 2. Create an article in that category
const articleRes = await fetch(`${BASE_URL}/articles`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    title: "How to create your first project",
    content: "## Welcome\n\nFollow these steps to get started:\n\n1. Click **New Project**\n2. Enter a name\n3. Choose a template\n\nThat's it!",
    categoryId: category.id,
    published: true,
  }),
});
const { data: article } = await articleRes.json();
console.log("Created:", article.title);

Authentication

All API requests require an API key sent via the X-API-Key header. Generate your API key from your dashboard under Settings > API Integration.

curl -X GET https://helpdeskhero.app/api/v1/categories \
  -H "X-API-Key: hdh_your_api_key_here"

Base URL: https://helpdeskhero.app/api/v1

Content Type: application/json

Categories

CRUD operations for organising articles into categories

GET /api/v1/categories

List all categories in your helpdesk

Example

curl -X GET https://helpdeskhero.app/api/v1/categories \
  -H "X-API-Key: hdh_your_api_key"

Response

{
  "data": [
    {
      "id": "abc123",
      "name": "Getting Started",
      "slug": "getting-started",
      "description": "Introductory guides",
      "icon": "folder",
      "order": 0
    }
  ]
}

POST /api/v1/categories

Create a new category

Request Body

{
  "name": "Getting Started",      // required
  "description": "Intro guides",  // optional
  "icon": "book-open"              // optional, default: "folder"
}

Example

curl -X POST https://helpdeskhero.app/api/v1/categories \
  -H "X-API-Key: hdh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Getting Started", "description": "Introductory guides"}'

Response

{
  "data": {
    "id": "abc123",
    "name": "Getting Started",
    "slug": "getting-started",
    "description": "Introductory guides",
    "icon": "folder",
    "order": 0
  }
}

PATCH /api/v1/categories/:id

Update a category. Only include the fields you want to change.

Request Body

{
  "name": "New Name",             // optional
  "description": "Updated desc",  // optional
  "icon": "star",                  // optional
  "order": 1                       // optional
}

Example

curl -X PATCH https://helpdeskhero.app/api/v1/categories/CATEGORY_ID \
  -H "X-API-Key: hdh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}'

Response

{
  "data": {
    "id": "abc123",
    "name": "Updated Name",
    "slug": "getting-started",
    "description": "Introductory guides",
    "icon": "folder",
    "order": 0
  }
}

DELETE /api/v1/categories/:id

Delete a category and all its articles

Example

curl -X DELETE https://helpdeskhero.app/api/v1/categories/CATEGORY_ID \
  -H "X-API-Key: hdh_your_api_key"

Response

{
  "data": {
    "success": true
  }
}

Articles

CRUD operations for managing helpdesk articles

GET /api/v1/articles

List all articles. Optionally filter by category using the categoryId query parameter.

Example

curl -X GET "https://helpdeskhero.app/api/v1/articles?categoryId=CATEGORY_ID" \
  -H "X-API-Key: hdh_your_api_key"

Response

{
  "data": [
    {
      "id": "def456",
      "title": "How to reset your password",
      "slug": "how-to-reset-your-password",
      "content": "## Steps\n\n1. Click **Forgot Password**...",
      "excerpt": "Learn how to reset your password",
      "published": true,
      "categoryId": "abc123",
      "order": 0
    }
  ]
}

POST /api/v1/articles

Create a new article. Content should be in Markdown format.

Request Body

{
  "title": "How to reset your password",  // required
  "content": "## Steps\n\n1. Click...",    // required, Markdown
  "slug": "reset-password",                // optional, auto-generated from title if omitted
  "excerpt": "Short summary",               // optional
  "categoryId": "abc123",                   // optional
  "published": true,                         // optional, default: false
  "numberHeadings": true                     // optional, default: false — numbers H2 headings
}

Example

curl -X POST https://helpdeskhero.app/api/v1/articles \
  -H "X-API-Key: hdh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "How to reset your password",
    "content": "## Steps\n\n1. Click **Forgot Password**\n2. Enter your email\n3. Check your inbox",
    "categoryId": "CATEGORY_ID",
    "published": true
  }'

Response

{
  "data": {
    "id": "def456",
    "title": "How to reset your password",
    "slug": "reset-password",
    "content": "## Steps\n\n1. Click **Forgot Password**...",
    "excerpt": null,
    "published": true,
    "numberHeadings": false,
    "categoryId": "abc123",
    "order": 0
  }
}

PATCH /api/v1/articles/:id

Update an article. Only include the fields you want to change. Changing the slug on a published article automatically creates a 301 redirect from the old URL.

Request Body

{
  "title": "Updated Title",       // optional
  "content": "New content...",     // optional, Markdown
  "slug": "new-url-handle",       // optional — auto-redirect created for published articles
  "excerpt": "Updated summary",   // optional
  "categoryId": "abc123",         // optional
  "published": true,               // optional
  "numberHeadings": true,          // optional — numbers H2 headings
  "order": 2                       // optional
}

Example

curl -X PATCH https://helpdeskhero.app/api/v1/articles/ARTICLE_ID \
  -H "X-API-Key: hdh_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"published": true}'

Response

{
  "data": {
    "id": "def456",
    "title": "How to reset your password",
    "slug": "new-url-handle",
    "content": "## Steps...",
    "published": true,
    "numberHeadings": true,
    "categoryId": "abc123",
    "order": 0
  }
}

DELETE /api/v1/articles/:id

Delete an article permanently

Example

curl -X DELETE https://helpdeskhero.app/api/v1/articles/ARTICLE_ID \
  -H "X-API-Key: hdh_your_api_key"

Response

{
  "data": {
    "success": true
  }
}

Error Responses

All errors return a JSON object with an error field:

401 Missing or invalid API key

{
  "error": "Missing X-API-Key header"
}

400 Missing required fields or invalid data

{
  "error": "Title is required"
}

404 Resource not found or doesn't belong to your helpdesk

{
  "error": "Category not found"
}

429 Rate limit exceeded (60 requests per minute per API key)

{
  "error": "Rate limit exceeded. Please try again later."
}

500 Server error

{
  "error": "Internal server error"
}

Markdown Formatting

Supported syntax for article content

Article content uses Markdown. In addition to standard syntax (headings, bold, italic, lists, links, images, code blocks), we support:

Tables

Use pipe syntax to create tables. The first row becomes the header.

| Feature     | Status    | Notes             |
| ----------- | --------- | ----------------- |
| Markdown    | Supported | Full GFM syntax   |
| Tables      | Supported | Auto-styled       |
| Callouts    | Supported | info/warning/danger |

Callout Blocks

Highlight important information with callout blocks using blockquote syntax:

> [!info]
> This is an informational note.

> [!warning]
> Be careful with this setting.

> [!danger]
> This action cannot be undone.

YouTube Embeds

Paste a YouTube URL on its own line to auto-embed the video:

https://www.youtube.com/watch?v=VIDEO_ID

Notes

Slugs

Slugs are auto-generated from the category name or article title and cannot be set or changed via the API. They are used in public helpdesk URLs (e.g. /help/your-site/how-to-reset-password).

Pagination

The API does not currently paginate results. All categories and articles are returned in a single response.

Filtering

Use the categoryId query parameter on GET /api/v1/articles to filter articles by category.

Rate Limiting

The API is limited to 60 requests per minute per API key. If you exceed this limit, you'll receive a 429 status code. Rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) are included in every response.

Category Icons

The following icon values are available for categories:

folder file-text book-open lightbulb help-circle settings zap users

The default icon is folder if none is specified.