Developer APIs

End-User API — Help Center & my tickets

The End-User API acts as a single authenticated employee. It has two controllers: Helpdesk_euapi serves the org-wide Help Center (read), and Helpdesk_tickets_euapi serves the caller's own tickets (read + write). Every ticket read/write is bound to selfUserId() (the JWT subject); a ticket is "mine" when its requested_by or created_by equals the caller.

GET /v1/api/me/help-articles

The org-wide Help Center is shared reference content, so this endpoint needs no permit beyond a valid session and is not self-scoped. Only active articles inside active, non-deleted categories are returned. Parameters: optional search (case-insensitive substring over title + body) and optional category_id (positive integer). Each item is {id, title, body, category}, where body is the article's HTML and category is the joined category title.

curl -s "https://app.erpat.example/v1/api/me/help-articles?search=leave" \
  -H "X-Company-Key: acme" \
  -H "Authorization: Bearer <employee-JWT>"

{
  "ok": true,
  "data": {
    "help_articles": [
      { "id": 7, "title": "Filing a leave request", "body": "<p>Go to…</p>", "category": "Leave" }
    ]
  }
}

GET /v1/api/me/tickets — list my tickets

Returns the caller's own tickets sorted by newest activity first (last_activity_at desc, then id). Optional filters:

Each ticket is shaped as: id, reference (derived TKT-{id}), subject (the title), category (joined ticket type), priority (from the labels CSV, default medium), status, agent (assigned user descriptor or null; online is always false), updated_at (localized), unread (always false), and messages (the single most-recent reply, or empty). A meta block carries page/per_page/total.

GET /v1/api/me/tickets/{id} — view one ticket

Returns the same ticket shape as the list, with messages expanded to the full reply thread. Each message is {id, author, author_name, body, sent_at}, where author is "me" when the caller wrote it and "agent" otherwise. A non-owned or missing id returns 404 ticket_not_found.

POST /v1/api/me/tickets — open a ticket

Requires the ticket_create permit. The new ticket's created_by and requested_by are always the authenticated employee — never read from input — and it is created with status new. The opening message becomes the ticket's first reply.

On success it returns 201 with {ticket_id, reference}.

curl -s -X POST "https://app.erpat.example/v1/api/me/tickets" \
  -H "X-Company-Key: acme" \
  -H "Authorization: Bearer <employee-JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Cannot access payslip portal",
    "message": "I get a 403 when opening my June payslip.",
    "priority": "high"
  }'

{
  "ok": true,
  "data": {
    "ticket_id": 1187,
    "reference": "TKT-1187"
  }
}

POST /v1/api/me/tickets/{id}/messages — reply

Requires the ticket_create permit. Ownership is verified before the body is read (so a non-owned id 404s first). The only body field is body (non-empty, required). The reply is appended to the ticket's thread and the ticket's last_activity_at is touched. Returns 201 with the created message.

curl -s -X POST "https://app.erpat.example/v1/api/me/tickets/1187/messages" \
  -H "X-Company-Key: acme" \
  -H "Authorization: Bearer <employee-JWT>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Still failing this morning — attaching a screenshot." }'

{
  "ok": true,
  "data": {
    "message": {
      "id": 5521,
      "author": "me",
      "author_name": "Juan Dela Cruz",
      "body": "Still failing this morning — attaching a screenshot.",
      "sent_at": "2026-07-02 08:41:12"
    }
  }
}