API docs by Redocly

Helpdesk module API (1.0.0)

Download OpenAPI specification:

Module-owned API fragment and source of truth for the helpdesk module's HTTP boundary: role tiers, assignment, status transitions, cross-module notification, and the at-least-one-admin-per-module invariant. It uses a different authz idiom from DocShare: tiers on the base company_module relations (member/editor/admin), no per-ticket tuples. All paths live under service.basePath (/api/helpdesk), with the major version inside the module's own path space (/v1).

Liveness probe. Served on the service's own listener, not under `/api/<module>`.

Authorizations:
bearerAuth

Responses

Readiness probe (database ping). Served on the service's own listener, not under `/api/<module>`.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

The caller's own helpdesk tier in this company (member/agent/admin) — membership-gated. Exists so the frontend can render tier-specific UI (agent/admin-only nav) without guessing from 403s.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Tickets the caller may see. view=mine (default): the tickets the caller reported. view=all: every ticket in the company; requires the agent or admin tier.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
query Parameters
view
string
Default: "mine"
Enum: "mine" "all"
status
string
Enum: "open" "in_progress" "resolved" "closed"

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Raise a ticket (helpdesk.tickets.create — membership-gated)

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
header Parameters
Idempotency-Key
string <= 200 characters
Request Body schema: application/json
required
title
required
string [ 1 .. 200 ] characters
description
required
string

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Read a ticket (reporter, agent, or admin — visibility enforced in service logic)

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

This ticket's audit trail (create, assign, status transitions) — the ticket detail page's status timeline. Same visibility rule as getTicket (reporter, agent, or admin).

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Assign a ticket to a member (helpdesk.manage — admin only). Assigning a non-agent auto-grants the agent tier (audited both).

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>
Request Body schema: application/json
required
assigneeMemberId
string <uuid>
assigneePositionId
string <uuid>
assigneeGroupId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "assigneeMemberId": "a87d6736-101e-47a4-aa83-1b9226d94242",
  • "assigneePositionId": "c3b2ae92-c359-4926-8d28-6259432cb0ad",
  • "assigneeGroupId": "c1685f07-9e3e-4e09-aed0-a00a4e21f38b"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Move a ticket's status (open->in_progress->resolved->closed, plus resolved->open reopen). assignee/admin progress+resolve; reporter/admin reopen a resolved ticket or close their own resolved ticket. Audited with from->to.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>
Request Body schema: application/json
required
status
required
string
Enum: "open" "in_progress" "resolved" "closed"

Responses

Request samples

Content type
application/json
{
  • "status": "open"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

A ticket's comment thread (reporter, agent, or admin on that ticket)

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Append a comment (reporter, agent, or admin on that ticket). Fires a notification event to the ticket's assignee (if the commenter is the reporter) or reporter (otherwise).

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
ticketId
required
string <uuid>
header Parameters
Idempotency-Key
string <= 200 characters
Request Body schema: application/json
required
body
required
string [ 1 .. 10000 ] characters

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Positions bound as helpdesk agents in this company, each with its current holder. Requires helpdesk.manage.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Groups bound as helpdesk agents in this company, each with its current member count. Requires helpdesk.manage.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List current agents (helpdesk.manage — admin only)

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Grant a member the agent tier (helpdesk.manage — admin only)

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
Request Body schema: application/json
required
memberId
string <uuid>
positionId
string <uuid>
groupId
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "memberId": "92983ab9-49c8-444b-85ae-6e40402cf72e",
  • "positionId": "da3402dc-13f8-45f9-83a6-bde06dd8eb35",
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Revoke a position's agent-tier binding (helpdesk.manage — admin only). Refuses (422) while any open ticket is assigned directly to that position, mirroring removeAgent's member-path rule.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
positionId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Revoke a group's agent-tier binding (helpdesk.manage — admin only). Refuses (422) while any open ticket is assigned directly to that group — the group sibling of removeAgentForPosition.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
groupId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Revoke a member's agent tier (helpdesk.manage — admin only). Refuses (422) to remove the tier from a member currently assigned any non-closed ticket (reassign first) — the protection rule; admin-tier revocation itself is out of scope for this module.

Authorizations:
bearerAuth
path Parameters
companyId
required
string <uuid>
memberId
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}