# 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.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `GET https://support-api.proxima.tools/api/unread`: Get unread tickets
- `GET https://support-api.proxima.tools/api/tickets`: List tickets
- `GET https://support-api.proxima.tools/api/tickets/{ticket_id}`: Retrieve a ticket
- `POST https://support-api.proxima.tools/api/tickets`: Create a ticket
- `POST https://support-api.proxima.tools/api/tickets/{ticket_id}/articles`: Reply to a ticket
- `POST https://support-api.proxima.tools/api/tickets/{ticket_id}/close`: Close a ticket
- `GET https://support-api.proxima.tools/api/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id}`: Download an attachment
- `GET https://support-api.proxima.tools/api/admin/tickets`: List all tickets (admin)
- `GET https://support-api.proxima.tools/api/admin/tickets/{ticket_id}`: Retrieve a ticket (admin)
- `POST https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles`: Reply to a ticket (admin)
- `POST https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/update`: Update a ticket (admin)
- `GET https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id}`: Download an attachment (admin)

## The SupportTicket object

A conversation as the customer sees it.

- `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: `new`, `open`, `pending reminder`, `pending close`, `closed`, `merged`.
- `priority` (enum): Ticket priority. Possible values: `low`, `normal`, `high`.
- `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.

```json
{
  "id": 1042,
  "number": "31042",
  "title": "Chart stays on the loading screen",
  "state": "open",
  "priority": "normal",
  "createdAt": "2026-10-28T14:03:11Z",
  "updatedAt": "2026-10-28T15:20:45Z",
  "lastAgentReplyAt": "2026-10-28T15:20:45Z",
  "closedAt": null,
  "articleCount": 3,
  "unread": true
}
```

## The SupportArticle object

One message in a ticket thread.

- `id` (integer): Article ID, used in attachment paths.
- `sender` (enum): Who wrote the message. Possible values: `agent`, `customer`.
- `author` (string): Display name of the author.
- `body` (string): Message body.
- `createdAt` (string): Creation timestamp.
- `attachments` (array<object>): Files attached to the message.
  - `id` (integer): Attachment ID.
  - `filename` (string): Original file name.
  - `size` (integer): Size in bytes.
  - `contentType` (string): MIME type.

```json
{
  "id": 88412,
  "sender": "agent",
  "author": "Proxima Support",
  "body": "Thanks, we can reproduce it. A fix is rolling out today.",
  "createdAt": "2026-10-28T15:20:45Z",
  "attachments": [
    {
      "id": 5521,
      "filename": "screenshot.png",
      "size": 184233,
      "contentType": "image/png"
    }
  ]
}
```

## The AdminSupportTicket object

A ticket as the admin inbox lists it.

- `id` (integer): Ticket ID.
- `number` (string): Human-readable ticket number.
- `title` (string): Subject line.
- `state` (enum): Zammad ticket state. Possible values: `new`, `open`, `pending reminder`, `pending close`, `closed`, `merged`.
- `priority` (enum): Ticket priority. Possible values: `low`, `normal`, `high`.
- `status` (enum): Whose turn it is. Possible values: `awaiting_agent`, `awaiting_customer`, `closed`.
- `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.

```json
{
  "id": 1042,
  "number": "31042",
  "title": "Chart stays on the loading screen",
  "state": "open",
  "priority": "normal",
  "status": "awaiting_agent",
  "customer": "degen_dev",
  "owner": null,
  "createdAt": "2026-10-28T14:03:11Z",
  "updatedAt": "2026-10-28T14:03:11Z",
  "articleCount": 1
}
```

### Get unread tickets

`GET https://support-api.proxima.tools/api/unread`

Returns how many tickets have unread agent replies, and which. (Bearer JWT)

- 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.

#### Returns 200 OK

- `count` (integer): Number of tickets with unread replies.
- `ticketIds` (array<integer>): IDs of those tickets.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/unread" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "count": 1,
  "ticketIds": [
    1042
  ]
}
```

### List tickets

`GET https://support-api.proxima.tools/api/tickets`

Lists the signed-in user's support tickets. (Bearer JWT)

- 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.

#### Returns 200 OK

- `tickets` (array<object>): The user's tickets, as `SupportTicket` objects.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/tickets" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "tickets": [
    {
      "id": 1042,
      "number": "31042",
      "title": "Chart stays on the loading screen",
      "state": "open",
      "priority": "normal",
      "createdAt": "2026-10-28T14:03:11Z",
      "updatedAt": "2026-10-28T15:20:45Z",
      "lastAgentReplyAt": "2026-10-28T15:20:45Z",
      "closedAt": null,
      "articleCount": 3,
      "unread": true
    }
  ]
}
```

### Retrieve a ticket

`GET https://support-api.proxima.tools/api/tickets/{ticket_id}`

Returns a ticket and its full message thread. (Bearer JWT)

- 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.

#### Returns 200 OK

- `ticket` (object): The `SupportTicket`.
- `articles` (array<object>): Messages in the thread, as `SupportArticle` objects.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/tickets/1042" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ticket": {
    "id": 1042,
    "number": "31042",
    "title": "Chart stays on the loading screen",
    "state": "open",
    "priority": "normal",
    "createdAt": "2026-10-28T14:03:11Z",
    "updatedAt": "2026-10-28T15:20:45Z",
    "lastAgentReplyAt": "2026-10-28T15:20:45Z",
    "closedAt": null,
    "articleCount": 2,
    "unread": false
  },
  "articles": [
    {
      "id": 88400,
      "sender": "customer",
      "author": "degen_dev",
      "body": "The chart on my launch never finishes loading.",
      "createdAt": "2026-10-28T14:03:11Z",
      "attachments": []
    },
    {
      "id": 88412,
      "sender": "agent",
      "author": "Proxima Support",
      "body": "Thanks, we can reproduce it. A fix is rolling out today.",
      "createdAt": "2026-10-28T15:20:45Z",
      "attachments": []
    }
  ]
}
```

### Create a ticket

`POST https://support-api.proxima.tools/api/tickets`

Opens a new support conversation, with optional files and a diagnostics bundle. (Bearer JWT)

- 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](/reference/support/#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

- `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

- `ticket` (object): The created `SupportTicket`.

#### Example request

```bash
curl -X POST "https://support-api.proxima.tools/api/tickets" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -F "title=<title>" \
  -F "body=<body>" \
  -F "diagnostics=<diagnostics>" \
  -F "display_name=<display_name>" \
  -F "files=@./image.png"
```

#### Example response

```json
{
  "ticket": {
    "id": 1043,
    "number": "31043",
    "title": "Chart stays on the loading screen",
    "state": "new",
    "priority": "normal",
    "createdAt": "2026-10-28T14:03:11Z",
    "updatedAt": "2026-10-28T14:03:11Z",
    "lastAgentReplyAt": null,
    "closedAt": null,
    "articleCount": 1,
    "unread": false
  }
}
```

### Reply to a ticket

`POST https://support-api.proxima.tools/api/tickets/{ticket_id}/articles`

Adds a customer message, with optional files, to a ticket. (Bearer JWT)

- 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](/reference/support/#retrieve-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.

#### Form fields

- `body` (string, required): Message text.
- `files` (file, optional): Attachment. Repeat the field once per file.

#### Returns 200 OK

- `article` (object): The created `SupportArticle`.

#### Example request

```bash
curl -X POST "https://support-api.proxima.tools/api/tickets/1042/articles" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -F "body=<body>" \
  -F "files=@./image.png"
```

#### Example response

```json
{
  "article": {
    "id": 88430,
    "sender": "customer",
    "author": "degen_dev",
    "body": "It works now, thanks!",
    "createdAt": "2026-10-28T16:02:09Z",
    "attachments": []
  }
}
```

### Close a ticket

`POST https://support-api.proxima.tools/api/tickets/{ticket_id}/close`

Closes a ticket on the customer's behalf. (Bearer JWT)

- 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.

#### Returns 200 OK

- `ticket` (object): The updated `SupportTicket`.

#### Example request

```bash
curl -X POST "https://support-api.proxima.tools/api/tickets/1042/close" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ticket": {
    "id": 1042,
    "number": "31042",
    "title": "Chart stays on the loading screen",
    "state": "closed",
    "priority": "normal",
    "createdAt": "2026-10-28T14:03:11Z",
    "updatedAt": "2026-10-28T16:05:00Z",
    "lastAgentReplyAt": "2026-10-28T15:20:45Z",
    "closedAt": "2026-10-28T16:05:00Z",
    "articleCount": 3,
    "unread": false
  }
}
```

### Download an attachment

`GET https://support-api.proxima.tools/api/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id}`

Returns the raw bytes of a file attached to a ticket message. (Bearer JWT)

- 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.
- `article_id` (integer, required): Article (message) ID.
- `attachment_id` (integer, required): Attachment ID.

#### Returns 200 OK

The file bytes. The content type is the attachment's own MIME type.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/tickets/1042/articles/88412/attachments/5521" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```text
<binary>
```

### List all tickets (admin)

`GET https://support-api.proxima.tools/api/admin/tickets`

Lists every ticket for the admin support inbox. (Admin JWT)

- 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.

#### Returns 200 OK

- `tickets` (array<object>): All tickets, as `AdminSupportTicket` objects.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/admin/tickets" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "tickets": [
    {
      "id": 1042,
      "number": "31042",
      "title": "Chart stays on the loading screen",
      "state": "open",
      "priority": "normal",
      "status": "awaiting_agent",
      "customer": "degen_dev",
      "owner": null,
      "createdAt": "2026-10-28T14:03:11Z",
      "updatedAt": "2026-10-28T14:03:11Z",
      "articleCount": 1
    }
  ]
}
```

### Retrieve a ticket (admin)

`GET https://support-api.proxima.tools/api/admin/tickets/{ticket_id}`

Returns a ticket and its full thread, including internal notes and system messages. (Admin JWT)

- 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.

#### Returns 200 OK

- `ticket` (object): The `AdminSupportTicket`.
- `articles` (array<object>): Thread messages.
  - `id` (integer): Article ID.
  - `sender` (enum): Who wrote the message. Possible values: `agent`, `customer`, `system`.
  - `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`.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/admin/tickets/1042" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```json
{
  "ticket": {
    "id": 1042,
    "number": "31042",
    "title": "Chart stays on the loading screen",
    "state": "open",
    "priority": "normal",
    "status": "awaiting_agent",
    "customer": "degen_dev",
    "owner": null,
    "createdAt": "2026-10-28T14:03:11Z",
    "updatedAt": "2026-10-28T14:03:11Z",
    "articleCount": 1
  },
  "articles": [
    {
      "id": 88400,
      "sender": "customer",
      "internal": false,
      "author": "degen_dev",
      "body": "The chart on my launch never finishes loading.",
      "createdAt": "2026-10-28T14:03:11Z",
      "attachments": [
        {
          "id": 5510,
          "filename": "diagnostics.json",
          "size": 48211,
          "contentType": "application/json"
        }
      ]
    }
  ]
}
```

### Reply to a ticket (admin)

`POST https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles`

Posts an agent reply or an internal note on a ticket. (Admin JWT)

- 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)](/reference/support/#admin-retrieve-ticket) and check whether it is in the thread.

#### Path parameters

- `ticket_id` (integer, required): Ticket ID.

#### Form fields

- `body` (string, required): Message text.
- `internal` (enum, required): `true` posts an internal note the customer does not see. Possible values: `true`, `false`.
- `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

- `article` (object): The created admin article (same shape as in Retrieve a ticket (admin)).

#### Example request

```bash
curl -X POST "https://support-api.proxima.tools/api/admin/tickets/1042/articles" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -F "body=<body>" \
  -F "internal=<internal>" \
  -F "author_name=<author_name>" \
  -F "files=@./image.png"
```

#### Example response

```json
{
  "article": {
    "id": 88412,
    "sender": "agent",
    "internal": false,
    "author": "Proxima Support",
    "body": "Thanks, we can reproduce it. A fix is rolling out today.",
    "createdAt": "2026-10-28T15:20:45Z",
    "attachments": []
  }
}
```

### Update a ticket (admin)

`POST https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/update`

Changes a ticket's state or priority, or snoozes it. (Admin JWT)

- 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.

#### Body parameters

- `state` (enum, optional): New state. Possible values: `open`, `closed`, `pending reminder`.
- `priority` (enum, optional): New priority. Possible values: `low`, `normal`, `high`.
- `pendingDays` (integer, optional): Reminder delay in days, used with `pending reminder`.
- `authorName` (string, optional): Agent name to record on the change.

#### Returns 200 OK

- `ticket` (object): The updated `AdminSupportTicket`.

#### Example request

```bash
curl -X POST "https://support-api.proxima.tools/api/admin/tickets/1042/update" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "state": "pending reminder",
  "pendingDays": 3
}'
```

#### Example response

```json
{
  "ticket": {
    "id": 1042,
    "number": "31042",
    "title": "Chart stays on the loading screen",
    "state": "pending reminder",
    "priority": "normal",
    "status": "awaiting_customer",
    "customer": "degen_dev",
    "owner": "Proxima Support",
    "createdAt": "2026-10-28T14:03:11Z",
    "updatedAt": "2026-10-28T16:10:00Z",
    "articleCount": 2
  }
}
```

### Download an attachment (admin)

`GET https://support-api.proxima.tools/api/admin/tickets/{ticket_id}/articles/{article_id}/attachments/{attachment_id}`

Returns the raw bytes of any attachment, including diagnostics bundles. (Admin JWT)

- 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.
- `article_id` (integer, required): Article (message) ID.
- `attachment_id` (integer, required): Attachment ID.

#### Returns 200 OK

The file bytes.

#### Example request

```bash
curl "https://support-api.proxima.tools/api/admin/tickets/1042/articles/88400/attachments/5510" \
  -H "Authorization: Bearer $PROXIMA_JWT"
```

#### Example response

```text
<binary>
```
