API Reference

The external API is mounted under /api/v1. Ticket endpoints remain the support operations foundation, while SupportHub also exposes broader CX platform resources through REST and GraphQL. Most endpoints require an active API client and the matching scope.

Authentication

curl -H "Authorization: Bearer shp_your_token" \
  http://localhost/supporthub/public/api/v1/tickets

Use either Authorization: Bearer or X-Api-Key. Missing tokens return 401. Inactive or invalid tokens return 401. Missing scopes return 403.

Idempotency

Mutating API requests can include Idempotency-Key. The app caches the response for the same client, endpoint, scope, and payload. Reusing a key for a different payload returns 409.

Ticket Endpoints

Method	Path	Scope	Purpose
GET	/tickets/lookups	tickets.read	Departments, categories, priorities, statuses, agents, organizations, tags, issue groups, context providers, and bulk actions.
POST	/tickets/suggestions/preview	tickets.read	Preview draft suggestions.
GET	/tickets	tickets.read	Paginated ticket list with filters.
POST	/tickets	tickets.write	Create an internal-style ticket.
POST	/tickets/requester-intake	tickets.write	Create a requester/public-style ticket.
GET	/tickets/{ticket}	tickets.read	Read ticket detail.
PUT	/tickets/{ticket}	tickets.write	Update ticket metadata and custom fields.
POST	/tickets/bulk-update	tickets.bulk	Bulk assign, department, status, or priority changes.
POST	/tickets/{ticket}/transition	tickets.transitions	Change ticket status.
POST	/tickets/{ticket}/reply	tickets.reply	Add customer-facing reply.
POST	/tickets/{ticket}/note	tickets.write	Add internal note.
POST	/tickets/{ticket}/attachments	tickets.attachments	Upload attachments.
GET	/tickets/{ticket}/attachments/{attachment}	tickets.attachments	Download an attachment.

CX Platform Endpoints

Method	Path	Scope	Purpose
GET	/customers	customers.read	Read Customer 360 profiles.
POST	/customers	customers.write	Create a customer/requester profile.
POST	/feedback	feedback.write	Create product feedback or roadmap input.
POST	/community	community.write	Create community discussions.
POST	/knowledge	knowledge.write	Create knowledge records for review.
POST	/status/components	status.write	Create or update public status components.
GET	/analytics/advanced	advanced_analytics.read	Read advanced analytics snapshots and forecasts.

GraphQL

/graphql accepts the same API key authentication and scope rules. For example, a token with customers.read and analytics.read can query customers and analytics summary data in one request.

Webhook Delivery Endpoints

Method	Path	Scope	Purpose
GET	/webhooks/deliveries	webhooks.read	List delivery records.
POST	/webhooks/deliveries/{webhookDelivery}/replay	webhooks.write	Replay an outbound delivery.
POST	/webhooks/inbound/ticket-updates	webhooks.write	Receive an external ticket update and map it to reply or note.

Create Ticket Example

curl -X POST http://localhost/supporthub/public/api/v1/tickets \
  -H "Authorization: Bearer shp_your_token" \
  -H "Idempotency-Key: create-ticket-1001" \
  -H "Accept: application/json" \
  -F "subject=Cannot login" \
  -F "description=The requester sees an access denied message." \
  -F "department_id=1" \
  -F "category_id=4" \
  -F "priority_id=2" \
  -F "status_id=1"

Public Update and Update Delivery APIs

The update service exposes license activation, remote update check, and update download endpoints under /api/v1. These are product-update endpoints, not general ticket integration endpoints. Do not expose update tokens beyond trusted update infrastructure.