API Reference

Supportly exposes authenticated operator APIs under /api/* plus widget-facing public endpoints authenticated with API keys and session tokens. Every route returns a standardized success or error envelope.

Standard response format

Success and error envelopes

success.jsonjson

1{
2  "success": true,
3  "data": {}
4}

Dashboard APIs use Clerk authentication and usually require the x-workspace-id header. Widget APIs use API keys and short-lived session tokens depending on the route.

GET /api/ai/models returns the combined model catalog: standard-provider models plus managed Pro presets. GET and PUT /api/ai/config include fallbackModel and allowModelFallback alongside the primary model selection.

Endpoint inventory

This list mirrors the current API contracts defined for the Supportly MVP.
Domain	Endpoints
Auth & onboarding	POST /api/webhooks/clerk, GET /api/onboarding, PUT /api/onboarding
Workspaces	GET /api/workspaces, POST /api/workspaces, GET/PATCH/DELETE /api/workspaces/[workspaceId]
AI	GET/PUT /api/ai/config, GET /api/ai/models, POST /api/ai/chat
Knowledge base	GET/POST /api/knowledge-base, PUT/DELETE /api/knowledge-base/[itemId], POST /api/knowledge-base/upload
Widget	GET /api/widget/config/[apiKey], POST /api/widget/session, POST /api/widget/chat, POST /api/widget/transcript
Conversations	GET /api/conversations, GET /api/conversations/[conversationId], GET/POST /api/conversations/[conversationId]/messages
Tickets	GET/POST /api/tickets, GET/PATCH /api/tickets/[ticketId], POST /api/tickets/[ticketId]/assign, GET/POST /api/tickets/[ticketId]/notes, POST /api/tickets/bulk
Team	GET /api/team, POST /api/team/invite, GET /api/team/invitations, POST /api/team/invitations/[invitationId], PATCH/DELETE /api/team/[memberId]
Notifications	GET /api/notifications, PATCH /api/notifications/[notificationId], POST /api/notifications/mark-all-read, GET/PUT /api/notifications/preferences
Analytics	GET /api/analytics/overview, GET /api/analytics/tickets, POST /api/analytics/export
API keys	GET/POST /api/api-keys, POST /api/api-keys/[keyId]/rotate, DELETE /api/api-keys/[keyId]
Taxonomy & SLA	GET/POST /api/categories, DELETE /api/categories/[categoryId], GET/POST /api/tags, DELETE /api/tags/[tagId], GET/PUT /api/sla
Uploads	POST /api/upload

Request and response examples

Create a ticket

Authenticated operator route example.

create-ticket.shbash

1curl -X POST "https://your-supportly-domain.com/api/tickets"   -H "Content-Type: application/json"   -H "x-workspace-id: 2e369db2-3ae8-4590-a59f-8c2777d0f43b"   -H "Authorization: Bearer <clerk-session>"   -d '{
2    "priority": "high",
3    "customerName": "Noura Ahmed",
4    "customerEmail": "noura@example.com",
5    "tagIds": ["b4a95cf9-661d-4c06-9f24-199f32613df1"]
6  }'

Fetch widget configuration

Public widget route example.

widget-config.shbash

1curl "https://your-supportly-domain.com/api/widget/config/ws_live_xxxxxxxxx"

Auth and workspace context

Surface	Auth	Workspace resolution
Dashboard routes	Clerk session	x-workspace-id header validated against membership
Widget config	API key in the URL path	Resolved from API key
Widget session and transcript	API key header plus session token when required	Resolved from API key and conversation state
Internal AI route	Internal caller	Explicit workspaceId in payload

One-time secret visibility

Full API keys are returned only when created or rotated. After that, Supportly exposes only the display prefix and revocation metadata.