Feedback API

This endpoint is hand-maintained, not generated by fetch-openapi.js — it's documented here alongside the other main-backend endpoints because it's the one part of the feedback feature a studio-facing integrator could reasonably call directly.

This backend has no local feedback_tickets table. POST /api/v1/feedback is a thin authenticated forwarder: it attaches the caller's studio identity and role, then relays the submission to Agon's central license server, which is the system of record for feedback tickets. That central service and its admin triage dashboard are founder-internal infrastructure, not part of the studio-facing API surface, and are not documented here — see Feedback for what a studio manager or staff member sees when using this feature from the desktop app.

---

POST /api/v1/feedback

Submit a bug report or feature request.

Authentication

Any authenticated staff account — Manager, Instructor, or a custom role. Unlike most staff-facing endpoints, this one is not restricted to Manager and carries no permission requirement beyond being logged in as staff.

Request body

multipart/form-data (not JSON — required to support optional file attachments).

Field	Required	Type	Description
type	Yes	string	"bug" or "feature".
title	Yes	string	Up to 200 characters.
description	Yes	string	Up to 5,000 characters.
files	No	file[]	0–3 attachments. Each up to 20MB. Allowed types: image/jpeg, image/png, image/webp, image/gif, video/mp4, video/quicktime (.mov), video/webm.

Responses

• 201

  {
    "id": "…",
    "type": "bug",
    "title": "Calendar crashes when I zoom in",
    "status": "submitted"
  }

• 409 FEEDBACK_NO_LICENSE — This install has not completed licensing setup yet (no license_key is configured), so there's no studio identity to attach the ticket to. Complete licensing before submitting feedback.

• 502 FEEDBACK_SERVICE_UNAVAILABLE — The call to the central feedback service failed or timed out (30s timeout, raised from the original 10s to accommodate attachment upload time), or that service returned an unexpected response. Safe to retry.

• 400 FEEDBACK_TOO_MANY_ATTACHMENTS — More than 3 files were sent in files.

• 400 FEEDBACK_ATTACHMENT_TOO_LARGE — One of the attached files is over 20MB.

• 400 FEEDBACK_ATTACHMENT_INVALID_TYPE — One of the attached files isn't an allowed image or video type. Returned whether the mismatch is in the extension, the declared Content-Type, or the file's actual content (checked against its extension via magic-byte/container-signature verification — a renamed file that doesn't actually match its extension is rejected here too).

• 422 — Validation error (missing type/title/description, invalid type, or a field over its length limit).

Notes

• Nothing is persisted locally — a successful submission (including any attachments) exists only on the central service from that point on. There's no GET endpoint to list or retrieve previously submitted feedback, or its attachments, from this backend.
• Every attachment is validated in full — filename sanitization, extension/content-type allow-list, and content verification — before anything is forwarded to the central service; the first invalid attachment aborts the whole submission, so partial uploads never happen.
• The request forwarded to the central service includes the studio's public studio id, studio name, and the caller's role name (e.g. "manager", "instructor", or a custom role's name) — never an individual staff member's name or email, and never any client, booking, or financial data beyond what the caller typed into title/description and chose to attach in files.
• The studio's license key is used only to authenticate the forwarded request server-to-server; it is never logged and never returned to the caller.

---

Related pages

• Feedback — the studio-facing guide for this feature
• License Server endpoints — the separate, centrally-hosted service this endpoint forwards to (its ticket-intake and admin-only endpoints are founder-internal and not documented as public API surface)