Annotations

Annotations are the core of Inpera - visual feedback pinned to specific elements on your website.

Creating Annotations

Via Overlay

1. Open your site with the Inpera overlay active
2. Click the annotation button
3. Click or drag to select an element
4. Enter your feedback
5. Submit

Via API

POST /annotations
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "projectId": "project-uuid",
  "content": "This button needs more contrast",
  "url": "https://example.com/page",
  "position_x": 150,
  "position_y": 320,
  "metadata": {
    "selector": "button.primary",
    "xpath": "/html/body/div/button",
    "text": "Submit"
  }
}

Annotation Properties

Field	Type	Description
id	string	Unique annotation ID
projectId	string	Parent project
content	string	Feedback text
url	string	Page URL
position_x	number	X coordinate
position_y	number	Y coordinate
status	string	open, in_progress, resolved
assigneeId	string	Assigned team member
metadata	object	DOM fingerprint data
createdAt	datetime	Creation timestamp

DOM Fingerprinting

Each annotation includes a DOM fingerprint for element rebinding:

{
  "selector": "button.primary",
  "xpath": "/html/body/div[1]/button[2]",
  "text": "Submit",
  "styles": {
    "backgroundColor": "#3b82f6",
    "fontSize": "14px"
  }
}

When the DOM changes, Inpera uses this fingerprint to relocate the annotation.

Annotation States

Status	Description
open	New, needs attention
in_progress	Being worked on
resolved	Completed

API Endpoints

List Annotations

GET /annotations/project/:projectId?url=optional-filter

Get Single Annotation

GET /annotations/:id

Update Status

PUT /annotations/:id/status
{
  "status": "resolved"
}

Assign to User

PUT /annotations/:id/assign
{
  "assigneeId": "user-uuid"
}

Rebind Element

POST /annotations/:id/rebind
{
  "domFingerprint": { ... }
}

Public Annotations

For unauthenticated feedback collection:

POST /annotations/public
Content-Type: application/json
x-project-key: YOUR_PROJECT_KEY

{
  "projectKey": "your-key",
  "content": "Feedback text",
  "url": "https://example.com",
  "position_x": 100,
  "position_y": 200
}