API

Use all Help Buddy functions (i.e. create tickets, delete tickets, view transcripts) via HTTPS

★

Premium Feature

The REST API requires the Custom tier. Create and manage keys in Developers → API.

API

Help Buddy allows you to perform many of its actions via HTTPS by using its very capable REST API.

This feature requires a Custom Buddy and Manage Server permissions in this guild.

https://helpbuddy.xyz/api/v1

Authentication

Create an API key in Developers → API. The key will only be shown once, so be sure you save it. Include it as an Authorization header on every request:

Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx

Keys carry scopes. A key needs the read scope for GET endpoints and the write scope for anything that changes data. A key whose server is no longer on an active Custom plan stops working automatically.

Rate limits

Each key is limited to 60 requests per minute by default. Exceeding it returns 429 with a Retry-After header. Your server's exact effective limit is shown in the API tab; it can only be changed by Help Buddy support (open a ticket in the Help Buddy Discord to request an adjustment).

Responses and errors

Responses are JSON. Errors use a consistent shape and standard HTTP status codes:

{ "error": { "code": "not_found", "message": "..." } }

Status	Meaning
`200` / `202`	Success, `202` means the action was queued for the bot
`400`	Invalid request body or parameters
`401`	Missing or invalid API key
`403`	Not a Custom server, or the key lacks the required scope
`404`	Resource not found
`429`	Rate limited

Actions on Discord (async)

Simple data state changes, such as editing a category or snippet and deleting a ticket, apply immediately. Writes that must happen on Discord, opening a ticket, posting a message, and closing a ticket, are performed by the bot. The API queues them and returns 202 with a command_id; the bot carries them out within a few seconds. Poll GET /commands/{id} to see the status and result (for example the new ticket id from an open).

Endpoints

Method	Route	Scope	Description
Utility
GET	`/id`	`read`	Key info: guild, scopes, and your effective rate limit
GET	`/stats`	`read`	Open / closed / deleted ticket counts and config totals
GET	`/commands/{id}`	`read`	Status and result of a queued command (open / message / close)
Tickets
GET	`/tickets`	`read`	List tickets, query: status, category, limit (max 100), cursor
GET	`/tickets/{id}`	`read`	Fetch a single ticket
GET	`/tickets/{id}/transcript`	`read`	The stored HTML transcript (text/html)
POST	`/tickets/{id}/messages`	`write`	Post a message into a ticket, queued (202)
POST	`/tickets/{id}/close`	`write`	Close a ticket, queued (202)
DELETE	`/tickets/{id}`	`write`	Delete a ticket (soft-delete, transcript retained; channel removed)
POST	`/tickets`	`write`	Open a ticket, queued (202); the creator must be a member of the server
Analytics
GET	`/analytics`	`read`	Aggregate ticket metrics (totals, by category, by tier)
Configuration
GET	`/panels`	`read`	List ticket panels (read-only via API)
GET	`/categories`	`read`	List categories
PUT	`/categories/{id}`	`write`	Update a category (label, emoji, welcome_text)
GET	`/snippets`	`read`	List snippets
PUT	`/snippets/{id}`	`write`	Update a snippet (label, emoji, content)

Examples

Every request needs the Authorization header. Requests that send a body also need Content-Type: application/json. Point your HTTP client (Postman, Insomnia, or your own code) at the endpoint below.

List open tickets

GET https://helpbuddy.xyz/api/v1/tickets?status=open&limit=20
Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx

Open-ticket count and other utilities

GET https://helpbuddy.xyz/api/v1/stats
Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx

Open a ticket

POST https://helpbuddy.xyz/api/v1/tickets
Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "creator_id": "223344556677889900",
  "tier": "free",
  "panel_id": "1508900000000000000",
  "category": "general",
  "fields": { "issue_desc": "Payment failed on checkout" }
}

All four of creator_id, tier, panel_id, and category are required. panel_id is what routes the ticket (thread vs channel and the welcome styling), and the category must be one that lives on that panel. creator_id must be a member of the server. Returns 202 with a command_id; poll GET /commands/{id} until status is done, and the result then contains the new ticket_id.

Post a message into a ticket

POST https://helpbuddy.xyz/api/v1/tickets/{ticket_id}/messages
Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "content": "A staff member will be with you shortly."
}

Close a ticket

POST https://helpbuddy.xyz/api/v1/tickets/{ticket_id}/close
Authorization: Bearer hb_live_xxxxxxxxxxxxxxxx

Panels

Panels are read-only via the API. Create and edit them from the dashboard.