API reference: screenshot uploads

Attaching an image to feedback is a two-step flow: upload the file here first, then include the returned screenshot object in the screenshots array of your POST /api/feedback call.

Request

Endpoint

POST https://usero.io/api/screenshots
Content-Type: multipart/form-data

CORS: Access-Control-Allow-Origin: *, callable directly from browsers and apps.
Auth: the clientId form field identifies your project. No API key.

Form fields

Field	Type	Required	Description
`screenshot`	file	yes	The image. Any `image/*` MIME type, 10MB max.
`clientId`	string	yes	Your project id. Must belong to an existing client.

One file per request. The widget allows up to 3 screenshots per feedback; if you need several, send several uploads.

Examples

curl -X POST https://usero.io/api/screenshots \
  -F "screenshot=@./bug.png" \
  -F "clientId=YOUR_CLIENT_ID"

Response

json

{
	"success": true,
	"screenshot": {
		"fileName": "client_abc/1717740000000-x7k2p.png",
		"url": "https://usero.io/api/screenshots/client_abc/1717740000000-x7k2p.png",
		"fileSize": 48211,
		"width": 1280,
		"height": 800,
		"mimeType": "image/png"
	}
}

Attach it to feedback

Pass the whole screenshot object inside the screenshots array when you submit the feedback:

curl -X POST https://usero.io/api/feedback \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "comment": "Button overlaps the footer, screenshot attached",
    "screenshots": [
      {
        "fileName": "client_abc/1717740000000-x7k2p.png",
        "url": "https://usero.io/api/screenshots/client_abc/1717740000000-x7k2p.png",
        "fileSize": 48211,
        "width": 1280,
        "height": 800,
        "mimeType": "image/png"
      }
    ]
  }'

Errors

Status	Body	Meaning and fix
400	`{"error": "Screenshot file is required"}`	The `screenshot` form field is missing.
400	`{"error": "Client ID is required"}`	The `clientId` form field is missing.
400	`{"error": "File must be an image"}`	The MIME type is not `image/*`.
400	`{"error": "File too large (max 10MB)"}`	The file exceeds 10MB.
403	`{"error": "Domain not allowed"}`	Your client has a domain allowlist and this origin is not on it.
404	`{"error": "Invalid client ID"}`	No client with that id exists. Check Find your clientId.
500	`{"error": "Failed to upload screenshot"}`	Something broke on our side. Safe to retry.