Annotations API

Annotations represent visual feedback pinned to specific elements on web pages.

Create Annotation

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

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

List Annotations by Project

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

Query parameters:

• url - Filter by page URL
• status - Filter by status

Get Single Annotation

GET /annotations/:id
Authorization: Bearer YOUR_TOKEN

Update Status

PUT /annotations/:id/status
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "status": "resolved"
}

Valid statuses:

• open
• in_progress
• resolved

Assign Annotation

PUT /annotations/:id/assign
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "assigneeId": "user-uuid"
}

Rebind Element

When the DOM changes, rebind the annotation to a new fingerprint:

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

{
  "domFingerprint": {
    "selector": "button.new-selector",
    "xpath": "/html/body/div/button",
    "text": "New Text"
  }
}

Public Endpoints

For unauthenticated feedback collection via the overlay:

Create Public Annotation

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

{
  "projectKey": "pk_xxx",
  "content": "Feedback text",
  "url": "https://example.com",
  "position_x": 100,
  "position_y": 200,
  "metadata": { ... }
}

List Public Annotations

GET /annotations/project/:projectKey/public?url=optional-filter