Skip to main content

API Reference

Helpdesk

Create helpdesk tickets from external sources like contact forms. Uses the secret key for authentication.

Create a Ticket

POST /api/v1/helpdesk/tickets Secret Key 10/min

Creates a new helpdesk conversation with an initial message. Finds or creates a contact by email and links to a company by email domain if one exists.

Parameters

Parameter Type Required Description
subject string Yes Ticket subject line
message string Yes Message body (plain text)
email string Yes Contact email address
name string No Contact name (defaults to email)
priority string No low, normal, high, or urgent (defaults to none)

Success Response (201)

{
  "id": 42,
  "subject": "Question about pricing",
  "state": "new",
  "priority": "normal",
  "contact": {
    "email": "visitor@example.com",
    "name": "Visitor"
  },
  "created_at": "2026-02-21T10:30:00Z"
}

Error Responses

// 401 Unauthorized
{ "error": "Invalid API key" }

// 404 Not Found (helpdesk not enabled)

// 422 Unprocessable Entity
{ "error": "subject is required" }
{ "error": "message is required" }
{ "error": "email is required" }
{ "error": "priority must be one of: low, normal, high, urgent" }

// 429 Too Many Requests (rate limited)

Example

curl -X POST https://squirrelstack.app/api/v1/helpdesk/tickets \
  -H "X-Api-Key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Question about pricing",
    "message": "Hi, I would like to know more about your pricing plans.",
    "email": "visitor@example.com",
    "name": "Visitor",
    "priority": "normal"
  }'