# Support API

This group covers the support tickets of the desks the caller works on: their fields, messages, status and assignees, and the links between tickets and project requests and tasks. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Tickets

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/ticket` | `support.ticket.getList` | Lists the support tickets of the desks the caller works on, filtered and paged. |
| GET | `/api/v1/ticket/{id}` | `support.ticket.get` | Gets a support ticket with its thread, as the caller's desk role lets them see it. |
| PUT | `/api/v1/ticket/{id}` | `support.ticket.updateFields` | Updates a ticket's subject, priority, category, routed project or custom fields. |
| POST | `/api/v1/ticket/{id}/assignee` | `support.ticket.addAssignee` | Assigns a person or agent to a ticket. |
| DELETE | `/api/v1/ticket/{id}/assignee/{principalType}/{principalId}` | `support.ticket.removeAssignee` | Removes an assignee from a ticket. |
| POST | `/api/v1/ticket/{id}/merge` | `support.ticket.merge` | Merges a ticket into another ticket of the same desk. |
| POST | `/api/v1/ticket/{id}/message` | `support.ticket.postMessage` | Adds a message to a ticket: an internal note for the team, or a reply the customer sees. |
| PUT | `/api/v1/ticket/{id}/message/{messageId}` | `support.ticket.editMessage` | Edits a message the caller wrote on a ticket. |
| DELETE | `/api/v1/ticket/{id}/message/{messageId}` | `support.ticket.deleteMessage` | Deletes a message from a ticket, the caller's own or one the desk lets them moderate. |
| POST | `/api/v1/ticket/{id}/status` | `support.ticket.changeStatus` | Changes the status of a ticket. |

Request bodies:

- `UpdateTicketFieldsDto` (`updateFields`): no field is required.

## Ticket links

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/ticket-link/request/{projectRequestId}` | `support.ticketLink.getForRequest` | Lists the support tickets linked to a project request the caller can read. |
| GET | `/api/v1/ticket-link/search-requests` | `support.ticketLink.searchRequests` | Searches the project requests a ticket can be linked to. |
| GET | `/api/v1/ticket-link/search-tasks` | `support.ticketLink.searchTasks` | Searches the project tasks a ticket can be linked to. |
| GET | `/api/v1/ticket-link/task/{projectTaskId}` | `support.ticketLink.getForTask` | Lists the support tickets linked to a project task the caller can read. |
| GET | `/api/v1/ticket-link/ticket/{ticketId}` | `support.ticketLink.getForTicket` | Lists the project requests and tasks a ticket is linked to. |
| GET | `/api/v1/ticket-link/ticket/{ticketId}/linkable-projects` | `support.ticketLink.getLinkableProjects` | Lists the projects of a ticket's desk the caller can work in, where its requests and tasks can be linked or created. |
| POST | `/api/v1/ticket-link/ticket/{ticketId}/requests` | `support.ticketLink.linkRequest` | Links a ticket to a project request that answers it. |
| DELETE | `/api/v1/ticket-link/ticket/{ticketId}/requests/{projectRequestId}` | `support.ticketLink.unlinkRequest` | Removes the link between a ticket and a project request. |
| POST | `/api/v1/ticket-link/ticket/{ticketId}/tasks` | `support.ticketLink.linkTask` | Links a ticket to a project task that answers it. |
| DELETE | `/api/v1/ticket-link/ticket/{ticketId}/tasks/{projectTaskId}` | `support.ticketLink.unlinkTask` | Removes the link between a ticket and a project task. |

## Example

`support.ticket.getList`: lists the support tickets of the desks the caller works on, filtered and paged.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/ticket?SkipCount=0&MaxResultCount=20" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```

`SkipCount` is how many items to skip and `MaxResultCount` how many to return. The answer carries `totalCount` and the page of `items`.
