vicket
Get started
API / NÂș 04

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

GroupAuthPurpose
GET /v1/mesessionCurrent user
/v1/orgssessionList, create orgs
/v1/orgs/{slug}sessionRead, update a specific org
/v1/orgs/{slug}/memberssessionInvite, list, role-set members
/v1/orgs/{slug}/sitessessionCRUD sites in an org
/v1/orgs/{slug}/statusessessionCRUD ticket statuses
/v1/orgs/{slug}/prioritiessessionCRUD priorities
/v1/orgs/{slug}/templatessessionCRUD ticket form templates
/v1/orgs/{slug}/workflowssessionCRUD workflows + run history
/v1/orgs/{slug}/help/articlessessionAuthor articles
/v1/orgs/{slug}/help/faqssessionAuthor FAQs
/v1/orgs/{slug}/ticketssessionAgent-facing ticket inbox
/support/v1/templatessite keyPublished ticket form templates
/support/v1/ticketssite keyPublic ticket submission
/support/v1/ticket?token=site key + tokenRead ticket thread via magic-link token
/support/v1/ticket/messages?token=site key + tokenPost a customer reply via magic-link token
/support/v1/ticket/attachments?token=site key + tokenInitiate file upload for a reply
/support/v1/help/articlessite keyPublished articles
/support/v1/help/faqssite keyPublished FAQs

Verbs and conventions

VerbEffect
GETRead. Idempotent.
POSTCreate. Returns the created resource with a server-issued ID.
PATCHPartial update. Send only fields you want to change.
PUTFull replace. Rare, used for workflow graphs.
DELETEDelete. 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 Origin or set X-Vicket-Origin: https://your-app.com on POST /support/v1/tickets so Vicket builds {origin}/ticket?token=... with your domain.
  • Templates: GET /support/v1/templates -> Template[], then GET /support/v1/templates/{key} -> { template, version, fields }.
  • Create ticket: POST /support/v1/tickets with { email, template_key, answers: [{ field_key, value_text | value_number | value_date | value_datetime | value_bool | value_array }] } (plus optional Idempotency-Key UUID). Returns 201 { 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 to upload_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