API Reference
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
1{2 "success": true,3 "data": {}4}Dashboard APIs use the Gegamo ONE session cookie 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
| Domain | Endpoints |
|---|---|
| Auth & onboarding | GET /api/auth/login, GET /api/auth/callback/gegamo, POST /api/auth/logout, GET/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 | GET/POST /api/categories, DELETE /api/categories/[categoryId], GET/POST /api/tags, DELETE /api/tags/[tagId] |
| Uploads | POST /api/upload |
Request and response examples
Create a ticket
Authenticated operator route example.
1await fetch("/api/tickets", {2 method: "POST",3 credentials: "same-origin",4 headers: {5 "Content-Type": "application/json",6 "x-workspace-id": "2e369db2-3ae8-4590-a59f-8c2777d0f43b",7 },8 body: JSON.stringify({9 priority: "high",10 customerName: "Noura Ahmed",11 customerEmail: "noura@example.com",12 tagIds: ["b4a95cf9-661d-4c06-9f24-199f32613df1"],13 }),14});Fetch widget configuration
Public widget route example.
1curl "https://your-supportly-domain.com/api/widget/config/ws_live_xxxxxxxxx"Auth and workspace context
| Surface | Auth | Workspace resolution |
|---|---|---|
| Dashboard routes | Gegamo ONE session cookie | 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 |
| Website customer issuance | Private server_identity Bearer key; backend only | POST /api/widget/auth/server-session derives workspace and paid eligibility from trusted records; JSON email, widgetKeyId, origin and optional customerName; 8 KiB maximum |
| Website browser identify | Public widget x-api-key, customer Bearer token, x-widget-bootstrap and browser origin | POST /api/widget/auth/identify binds the customer to the issuing workspace, public widget and verified origin |
| Customer logout | Customer Bearer token | POST /api/widget/auth/logout revokes website sessions individually; call resetIdentity on website logout |
| 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.
Select exactly one customerLoginMethod: email_codes or website_auto_login. Website auto login is paid only and has no Supportly email-code fallback. Private keys never authorize dashboard access or public widget loading. Read /docs/website-auto-login for the email trust boundary, CSRF requirements, refresh/logout lifecycle and complete limits. Never enter private keys or customer tokens in the browser API playground.