Skip to content
API Reference

Search is only available in production builds. Try building and previewing the site to test it out locally.

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.

A conversation as the customer sees it.

Attributes

  • id integer
    Ticket ID, used in every {ticket_id} path.
  • number string
    Human-readable ticket number.
  • title string
    Subject line.
  • state enum
    Zammad ticket state.
    Possible values newopenpending reminderpending closeclosedmerged
  • priority enum
    Ticket priority.
    Possible values lownormalhigh
  • createdAt string
    Creation timestamp.
  • updatedAt string
    Last update timestamp.
  • lastAgentReplyAt string | null
    Time of the last agent reply, null if none.
  • closedAt string | null
    Close time, null while open.
  • articleCount integer
    Number of messages in the thread.
  • unread boolean
    Whether the thread has agent replies the user has not read.

One message in a ticket thread.

Attributes

  • id integer
    Article ID, used in attachment paths.
  • sender enum
    Who wrote the message.
    Possible values agentcustomer
  • author string
    Display name of the author.
  • body string
    Message body.
  • createdAt string
    Creation timestamp.
  • attachments array<object>
    Files attached to the message.
    Child attributes 4
    • id integer
      Attachment ID.
    • filename string
      Original file name.
    • size integer
      Size in bytes.
    • contentType string
      MIME type.

A ticket as the admin inbox lists it.

Attributes

  • id integer
    Ticket ID.
  • number string
    Human-readable ticket number.
  • title string
    Subject line.
  • state enum
    Zammad ticket state.
    Possible values newopenpending reminderpending closeclosedmerged
  • priority enum
    Ticket priority.
    Possible values lownormalhigh
  • status enum
    Whose turn it is.
    Possible values awaiting_agentawaiting_customerclosed
  • customer string
    Customer display name.
  • owner string | null
    Assigned agent, null when unassigned.
  • createdAt string
    Creation timestamp.
  • updatedAt string
    Last update timestamp.
  • articleCount integer | null
    Number of messages, null when unknown.

Get unread tickets

Bearer JWT
GET 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

  • count integer
    Number of tickets with unread replies.
  • ticketIds array<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

Bearer JWT
GET 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

  • tickets array<object>
    The user's tickets, as SupportTicket objects.

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

Bearer JWT
GET 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_id integer Required
    Ticket ID.
    Example1042

Returns 200 OK · application/json

  • ticket object
    The SupportTicket.
  • articles array<object>
    Messages in the thread, as SupportArticle objects.

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

Bearer JWT
POST 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

  • title string Required
    Subject line.
  • body string Required
    First message.
  • diagnostics string Required
    Redacted diagnostics JSON, serialized as a string. Empty string if collection failed.
  • display_name string Optional
    Name shown for the customer. Omitted when unknown.
  • files file Optional
    Attachment. Repeat the field once per file.

Returns 200 OK · application/json

  • ticket object
    The created SupportTicket.

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

Bearer JWT
POST 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_id integer Required
    Ticket ID.
    Example1042

Form fields multipart/form-data

  • body string Required
    Message text.
  • files file Optional
    Attachment. Repeat the field once per file.

Returns 200 OK · application/json

  • article object
    The created SupportArticle.

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

Bearer JWT
POST 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_id integer Required
    Ticket ID.
    Example1042

Returns 200 OK · application/json

  • ticket object
    The updated SupportTicket.

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

GET 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_id integer Required
    Ticket ID.
    Example1042
  • article_id integer Required
    Article (message) ID.
    Example88412
  • attachment_id integer Required
    Attachment 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

GET 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

  • tickets array<object>
    All tickets, as AdminSupportTicket objects.

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

GET 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_id integer Required
    Ticket ID.
    Example1042

Returns 200 OK · application/json

  • ticket object
    The AdminSupportTicket.
  • articles array<object>
    Thread messages.
    Child attributes 7
    • id integer
      Article ID.
    • sender enum
      Who wrote the message.
      Possible values agentcustomersystem
    • internal boolean
      Internal note, hidden from the customer.
    • author string
      Display name of the author.
    • body string
      Message body.
    • createdAt string
      Creation timestamp.
    • attachments array<object>
      Attachments (id, filename, size, contentType). Admins also see diagnostics.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

POST 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_id integer Required
    Ticket ID.
    Example1042

Form fields multipart/form-data

  • body string Required
    Message text.
  • internal enum Required
    true posts an internal note the customer does not see.
    Possible values truefalse
  • author_name string Optional
    Name to sign the reply with. Omitted when not set.
  • files file Optional
    Attachment. Repeat the field once per file.

Returns 200 OK · application/json

  • article object
    The 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

POST 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_id integer Required
    Ticket ID.
    Example1042

Body parameters application/json

  • state enum Optional
    New state.
    Possible values openclosedpending reminder
  • priority enum Optional
    New priority.
    Possible values lownormalhigh
  • pendingDays integer Optional
    Reminder delay in days, used with pending reminder.
  • authorName string Optional
    Agent name to record on the change.

Returns 200 OK · application/json

  • ticket object
    The updated AdminSupportTicket.

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

GET 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_id integer Required
    Ticket ID.
    Example1042
  • article_id integer Required
    Article (message) ID.
    Example88400
  • attachment_id integer Required
    Attachment 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