GatherlyDocs

Documentation

Feedback API

POST /api/feedback request and response shape.

Endpoint

The embed posts here. You can call the same endpoint from your own client if you need a custom UI.

http
POST /api/feedback
Content-Type: application/json

CORS allows any origin with POST and OPTIONS.

Request body

json
{
  "key": "pk_live_…",
  "type": "feedback",
  "message": "Love the new onboarding flow.",
  "description": "The checklist made setup much clearer.",
  "email": "alex@acme.com",
  "username": "alex",
  "userId": "usr_123",
  "featureId": "…",
  "originUrl": "https://app.acme.com/settings",
  "screenResolution": "1920x1080"
}
FieldRequiredNotes
keyYesProject public key; must start with pk_
typeYesfeedback, bug, or feature
messageYesShort title. Non-empty, max 5000 characters. title is accepted as an alias.
descriptionNoLonger details; max 5000 characters
emailNoVisitor or identified email
usernameNoDisplay name / handle
userIdNoYour app's user id
featureIdNoId of a feature from Project → Features; must belong to this project
originUrlNoPage the user was on when submitting; widget sends location.href. pageUrl is accepted as an alias.
screenResolutionNoClient screen size, e.g. 1920x1080. Widget sends screen.width×screen.height. Max 32 characters.
attachmentIdsNoBug reports only. Up to 5 ids from POST /api/feedback/attachment-uploads. Requires a verified identity token. See Image attachments below.
User-AgentAutoTaken from the request header. Gatherly stores the raw value and derives browser (Chrome, Safari, …), device (PC, Phone, Tablet, TV, …), and os (Windows, macOS, iOS, …) for the inbox.

Image attachments (bugs)

Authenticated users can attach up to five JPEG or PNG images (5MB each) to a bug report. Uploads go directly to private storage via signed URLs so large files do not pass through the feedback API.

  1. Call POST /api/feedback/attachment-uploads with your project key, identity token, and file metadata.
  2. PUT each file to the returned signedUrl.
  3. Submit POST /api/feedback with type: "bug" and attachmentIds.
http
POST /api/feedback/attachment-uploads
Content-Type: application/json
Authorization: Bearer <identity-jwt>
json
{
  "key": "pk_live_…",
  "files": [
    { "contentType": "image/png", "sizeBytes": 204800 }
  ]
}
json
{
  "attachments": [
    {
      "id": "…",
      "path": "…",
      "token": "…",
      "signedUrl": "https://…"
    }
  ]
}
  • Requires project user authentication enabled and a valid identity JWT. Anonymous users can still submit text-only bugs.
  • Rate limit: one image-bearing bug submit per authenticated user per project every 10 minutes.
  • Images are deleted after the project retention period (default 30 days; configurable under Project → Widget).

Success response

json
HTTP/1.1 201 Created

{
  "id": "…",
  "ok": true
}

Error responses

  • 400 — invalid JSON, missing message, invalid type, unknown feature, or invalid attachments
  • 401 — missing / invalid / unknown project key or identity token
  • 403 — audience rules, attaching images without authentication, or monthly response quota reached
  • 429 — too many submissions from this client, or image attachment rate limit
  • 500 — failed to persist the message
json
{ "error": "Message (title) is required (max 5000 characters)." }