API endpoints
The Vicket API is REST, JSON, versioned at /v1 for the dashboard surface and /support/v1 for the public surface your support page calls. All endpoints return a stable envelope: data on success, { "error": { "code", "message" } } on failure. Authentication rules are in api-authentication.
Endpoint groups
| Group | Auth | Purpose |
|---|---|---|
GET /v1/me | session | Current user |
/v1/orgs | session | List, create orgs |
/v1/orgs/{slug} | session | Read, update a specific org |
/v1/orgs/{slug}/members | session | Invite, list, role-set members |
/v1/orgs/{slug}/sites | session | CRUD sites in an org |
/v1/orgs/{slug}/statuses | session | CRUD ticket statuses |
/v1/orgs/{slug}/priorities | session | CRUD priorities |
/v1/orgs/{slug}/templates | session | CRUD ticket form templates |
/v1/orgs/{slug}/workflows | session | CRUD workflows + run history |
/v1/orgs/{slug}/help/articles | session | Author articles |
/v1/orgs/{slug}/help/faqs | session | Author FAQs |
/v1/orgs/{slug}/tickets | session | Agent-facing ticket inbox |
/support/v1/templates | site key | Published ticket form templates |
/support/v1/tickets | site key | Public ticket submission |
/support/v1/ticket?token= | site key + token | Read ticket thread via magic-link token |
/support/v1/ticket/messages?token= | site key + token | Post a customer reply via magic-link token |
/support/v1/ticket/attachments?token= | site key + token | Initiate file upload for a reply |
/support/v1/help/articles | site key | Published articles |
/support/v1/help/faqs | site key | Published FAQs |
Verbs and conventions
| Verb | Effect |
|---|---|
GET | Read. Idempotent. |
POST | Create. Returns the created resource with a server-issued ID. |
PATCH | Partial update. Send only fields you want to change. |
PUT | Full replace. Rare, used for workflow graphs. |
DELETE | Delete. 204 on success. |
Idempotency
POST /support/v1/tickets accepts an optional Idempotency-Key header. The same key with the same body returns the cached response; the same key with a different body returns 409. The scaffolded components send a UUID per submission so accidental double-clicks are safe.
Customer magic-link flow (/ticket?token=)
When a ticket is submitted via POST /support/v1/tickets, Vicket issues a 30-day magic-link token and emails {origin}/ticket?token=... to the requester (using the request Origin / X-Vicket-Origin or the site's first allowed origin). The customer stays on your domain to view the thread (GET /support/v1/ticket?token=...), post replies (POST /support/v1/ticket/messages?token=...), and upload attachments (POST /support/v1/ticket/attachments?token=...).
Proxying /support/v1/* from your own backend
If you proxy /support/v1/* through your own BFF instead of calling api.vicket.app directly from the browser:
- Required header:
X-Vicket-Key: pk_... - Recommended header: forward the browser's
Originor setX-Vicket-Origin: https://your-app.comonPOST /support/v1/ticketsso Vicket builds{origin}/ticket?token=...with your domain. - Templates:
GET /support/v1/templates->Template[], thenGET /support/v1/templates/{key}->{ template, version, fields }. - Create ticket:
POST /support/v1/ticketswith{ email, template_key, answers: [{ field_key, value_text | value_number | value_date | value_datetime | value_bool | value_array }] }(plus optionalIdempotency-KeyUUID). Returns201 { ticket_id, public_number, subject, score, priority_key, status_key }. - Read thread:
GET /support/v1/ticket?token=...->{ ticket, answers, comments }. - Post reply:
POST /support/v1/ticket/messages?token=...with{ body_markdown }->201 Comment(returns{ id, ... }). - Upload attachment:
POST /support/v1/ticket/attachments?token=...with{ comment_id, filename, mime_type, size_bytes }->201 { attachment, upload_grant: { upload_url, method, key, headers } }, then upload the file toupload_grant.upload_url.
Go backend proxy example
func proxyToVicket(w http.ResponseWriter, r *http.Request, method, path string, query url.Values) {
target := "https://api.vicket.app" + path
if len(query) > 0 {
target += "?" + query.Encode()
}
req, _ := http.NewRequestWithContext(r.Context(), method, target, r.Body)
req.Header.Set("X-Vicket-Key", os.Getenv("VICKET_API_KEY"))
if origin := r.Header.Get("Origin"); origin != "" {
req.Header.Set("X-Vicket-Origin", origin)
}
if ct := r.Header.Get("Content-Type"); ct != "" {
req.Header.Set("Content-Type", ct)
}
if ik := r.Header.Get("Idempotency-Key"); ik != "" {
req.Header.Set("Idempotency-Key", ik)
}
resp, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
if err != nil {
http.Error(w, "upstream unavailable", http.StatusBadGateway)
return
}
defer resp.Body.Close()
w.Header().Set("Content-Type", resp.Header.Get("Content-Type"))
w.WriteHeader(resp.StatusCode)
io.Copy(w, resp.Body)
}
Next.js / React / Vue / SvelteKit / Astro direct fetch example
const res = await fetch("https://api.vicket.app/support/v1/tickets", {
method: "POST",
headers: {
"X-Vicket-Key": process.env.NEXT_PUBLIC_VICKET_SITE_KEY!, // or import.meta.env.VITE_VICKET_SITE_KEY / PUBLIC_VICKET_SITE_KEY
"Content-Type": "application/json",
"Idempotency-Key": crypto.randomUUID(),
},
body: JSON.stringify({
email: "user@example.com",
template_key: "tmpl-...",
answers: [{ field_key: "subject", value_text: "Need help" }],
}),
});
Rate limits
Public endpoints are rate limited per site and per IP. Exceeding the limit returns 429; back off and retry.
Example: list published articles
GET /support/v1/help/articles HTTP/1.1
Host: api.vicket.app
X-Vicket-Key: pk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0
Next
- Outbound from us to you: webhooks.
- Auth specifics: api-authentication.