Support
Open, read and answer support conversations backed by Zammad through the Proxima support worker.
The support API is served by a separate Cloudflare worker (proxima-support-cf) that fronts a Zammad helpdesk. It lives on its own host, https://support-api.proxima.tools, and every path is prefixed with /api.
Every call sends the user's Proxima session JWT as Authorization: Bearer <JWT>. Errors come back as a JSON body { "error": string, "code"?: string }; the web client surfaces error as the message. The /api/admin/* routes are only called from the admin support page (/admin/support).
The web client polls instead of streaming: unread counts every 60 seconds, ticket lists and open threads every 20 seconds, and again on window focus.
- GET
https://support-api.proxima.tools/api/unread - GET
https://support-api.proxima.tools/api/tickets - GET
https://support-api.proxima.tools/api/tickets/{ticket_id} - POST
https://support-api.proxima.tools/api/tickets - POST
https://support-api.proxima.tools/api/tickets/{ticket_id}/articles - POST
https://support-api.proxima.tools/api/tickets/{ticket_id}/close - GET
https://support-api.proxima.tools/api/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id} - GET
https://support-api.proxima.tools/api/admin/tickets - GET
https://support-api.proxima.tools/api/admin/tickets/{ticket_id} - POST
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles - POST
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/update - GET
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id}
The SupportTicket object
A conversation as the customer sees it.
Attributes
-
idintegerTicket ID, used in every{ticket_id}path. -
numberstringHuman-readable ticket number. -
titlestringSubject line. -
stateenumZammad ticket state.Possible valuesnewopenpending reminderpending closeclosedmerged -
priorityenumTicket priority.Possible valueslownormalhigh -
createdAtstringCreation timestamp. -
updatedAtstringLast update timestamp. -
lastAgentReplyAtstring | nullTime of the last agent reply,nullif none. -
closedAtstring | nullClose time,nullwhile open. -
articleCountintegerNumber of messages in the thread. -
unreadbooleanWhether the thread has agent replies the user has not read.
The SupportArticle object
One message in a ticket thread.
Attributes
-
idintegerArticle ID, used in attachment paths. -
senderenumWho wrote the message.Possible valuesagentcustomer -
authorstringDisplay name of the author. -
bodystringMessage body. -
createdAtstringCreation timestamp. -
attachmentsarray<object>Files attached to the message.Child attributes 4
-
idintegerAttachment ID. -
filenamestringOriginal file name. -
sizeintegerSize in bytes. -
contentTypestringMIME type.
-
A ticket as the admin inbox lists it.
Attributes
-
idintegerTicket ID. -
numberstringHuman-readable ticket number. -
titlestringSubject line. -
stateenumZammad ticket state.Possible valuesnewopenpending reminderpending closeclosedmerged -
priorityenumTicket priority.Possible valueslownormalhigh -
statusenumWhose turn it is.Possible valuesawaiting_agentawaiting_customerclosed -
customerstringCustomer display name. -
ownerstring | nullAssigned agent,nullwhen unassigned. -
createdAtstringCreation timestamp. -
updatedAtstringLast update timestamp. -
articleCountinteger | nullNumber of messages,nullwhen unknown.
Get unread tickets
https://support-api.proxima.tools/api/unread Served outside the main API host.
Returns how many tickets have unread agent replies, and which.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Drives the badge on the support icon. Polled every 60 seconds and on window focus.
Parameters
No parameters.
Returns 200 OK · application/json
-
countintegerNumber of tickets with unread replies. -
ticketIdsarray<integer>IDs of those tickets.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.
Web client fetchUnread(jwt) src/lib/support/api.ts
List tickets
https://support-api.proxima.tools/api/tickets Served outside the main API host.
Lists the signed-in user's support tickets.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Polled every 20 seconds while the support page is open.
Parameters
No parameters.
Returns 200 OK · application/json
-
ticketsarray<object>The user's tickets, asSupportTicketobjects.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.
Web client fetchTickets(jwt) src/lib/support/api.ts
Retrieve a ticket
https://support-api.proxima.tools/api/tickets/{ticket_id} Served outside the main API host.
Returns a ticket and its full message thread.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
After a successful read the web client marks the ticket as read in its local cache. It also hides any attachment named diagnostics.json (the diagnostics bundle sent on creation) from the thread.
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Returns 200 OK · application/json
-
ticketobjectTheSupportTicket. -
articlesarray<object>Messages in the thread, asSupportArticleobjects.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.
Web client fetchTicket(jwt, ticketId) src/lib/support/api.ts
Create a ticket
https://support-api.proxima.tools/api/tickets Served outside the main API host.
Opens a new support conversation, with optional files and a diagnostics bundle.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying Each call opens a new ticket. Before retrying, call List tickets and check whether the ticket was created.
Sent as multipart/form-data. The web client attaches a redacted diagnostics JSON string (page, app version, device, recent console logs, Sentry breadcrumbs, local/session storage with sensitive keys filtered) built by buildDiagnostics() in src/lib/bugReport/collect.ts.
Client-side limits (from src/config/support.ts): title up to 200 characters, message 3 to 8000 characters, at most 5 files of 25 MiB each. Whether the worker enforces the same limits is not visible from the client.
Form fields multipart/form-data
-
titlestring RequiredSubject line. -
bodystring RequiredFirst message. -
diagnosticsstring RequiredRedacted diagnostics JSON, serialized as a string. Empty string if collection failed. -
display_namestring OptionalName shown for the customer. Omitted when unknown. -
filesfile OptionalAttachment. Repeat the field once per file.
Returns 200 OK · application/json
-
ticketobjectThe createdSupportTicket.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client createTicket(jwt, { title, body, files, diagnostics, displayName }) src/lib/support/api.ts
Reply to a ticket
https://support-api.proxima.tools/api/tickets/{ticket_id}/articles Served outside the main API host.
Adds a customer message, with optional files, to a ticket.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying Each call posts a new message. Before retrying, call Retrieve a ticket and check whether the reply is in the thread.
After a successful reply to a closed ticket, the web client shows it as open locally before refetching.
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Form fields multipart/form-data
-
bodystring RequiredMessage text. -
filesfile OptionalAttachment. Repeat the field once per file.
Returns 200 OK · application/json
-
articleobjectThe createdSupportArticle.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client replyToTicket(jwt, ticketId, { body, files }) src/lib/support/api.ts
Close a ticket
https://support-api.proxima.tools/api/tickets/{ticket_id}/close Served outside the main API host.
Closes a ticket on the customer's behalf.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Closing a closed ticket leaves it closed.
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Returns 200 OK · application/json
-
ticketobjectThe updatedSupportTicket.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required), 403 read_only_token and 429 when rate limited.
Web client closeTicket(jwt, ticketId) src/lib/support/api.ts
Download an attachment
https://support-api.proxima.tools/api/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id} Served outside the main API host.
Returns the raw bytes of a file attached to a ticket message.
- Token
- Upgraded session token, bound to a license.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
The web client reads the body as a Blob and caches it for the session. Any non-2xx status is reported as "Could not load attachment".
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042 -
article_idinteger RequiredArticle (message) ID.Example88412 -
attachment_idinteger RequiredAttachment ID.Example5521
Returns 200 OK · application/octet-stream
The file bytes. The content type is the attachment's own MIME type.
Errors
Only the common errors: 401 for a missing or expired session or a base token (license_required) and 429 when rate limited.
Web client fetchAttachmentBlob(jwt, ticketId, articleId, attachmentId) src/lib/support/api.ts
List all tickets (admin)
https://support-api.proxima.tools/api/admin/tickets Served outside the main API host.
Lists every ticket for the admin support inbox.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Called from the admin support page with the admin's Proxima JWT. Polled every 20 seconds.
Parameters
No parameters.
Returns 200 OK · application/json
-
ticketsarray<object>All tickets, asAdminSupportTicketobjects.
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client fetchAdminTickets(jwt) src/lib/support/api.ts
Retrieve a ticket (admin)
https://support-api.proxima.tools/api/admin/tickets/{ticket_id} Served outside the main API host.
Returns a ticket and its full thread, including internal notes and system messages.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Returns 200 OK · application/json
-
ticketobjectTheAdminSupportTicket. -
articlesarray<object>Thread messages.Child attributes 7
-
idintegerArticle ID. -
senderenumWho wrote the message.Possible valuesagentcustomersystem -
internalbooleanInternal note, hidden from the customer. -
authorstringDisplay name of the author. -
bodystringMessage body. -
createdAtstringCreation timestamp. -
attachmentsarray<object>Attachments (id,filename,size,contentType). Admins also seediagnostics.json.
-
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client fetchAdminTicket(jwt, ticketId) src/lib/support/api.ts
Reply to a ticket (admin)
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles Served outside the main API host.
Posts an agent reply or an internal note on a ticket.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Check before retrying Each call posts a new message or note. Before retrying, call Retrieve a ticket (admin) and check whether it is in the thread.
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Form fields multipart/form-data
-
bodystring RequiredMessage text. -
internalenum Requiredtrueposts an internal note the customer does not see.Possible valuestruefalse -
author_namestring OptionalName to sign the reply with. Omitted when not set. -
filesfile OptionalAttachment. Repeat the field once per file.
Returns 200 OK · application/json
-
articleobjectThe created admin article (same shape as in Retrieve a ticket (admin)).
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client replyToAdminTicket(jwt, ticketId, { body, files, internal, authorName }) src/lib/support/api.ts
Update a ticket (admin)
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/update Served outside the main API host.
Changes a ticket's state or priority, or snoozes it.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Refused with
403 read_only_token. - Retry
- Safe to retry Sending the same update again leaves the ticket in the same state.
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042
Body parameters application/json
-
stateenum OptionalNew state.Possible valuesopenclosedpending reminder -
priorityenum OptionalNew priority.Possible valueslownormalhigh -
pendingDaysinteger OptionalReminder delay in days, used withpending reminder. -
authorNamestring OptionalAgent name to record on the change.
Returns 200 OK · application/json
-
ticketobjectThe updatedAdminSupportTicket.
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role, 403 read_only_token and 429 when rate limited.
Web client updateAdminTicket(jwt, ticketId, input) src/lib/support/api.ts
Download an attachment (admin)
https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id} Served outside the main API host.
Returns the raw bytes of any attachment, including diagnostics bundles.
- Token
- Upgraded session token of an account with admin rights.
- Read-only tokens
- Allowed.
- Retry
- Safe to retry
Path parameters
-
ticket_idinteger RequiredTicket ID.Example1042 -
article_idinteger RequiredArticle (message) ID.Example88400 -
attachment_idinteger RequiredAttachment ID.Example5510
Returns 200 OK · application/octet-stream
The file bytes.
Errors
Only the common errors: 401 for a missing or expired session, 403 forbidden without the admin role and 429 when rate limited.
Web client fetchAttachmentBlob(jwt, ticketId, articleId, attachmentId, true) src/lib/support/api.ts