API

Programmatic access for developers

Overview

Agentation exposes callbacks that let you integrate annotations into your own workflows — send to a backend, pipe to terminal, trigger automations, or build custom AI integrations.

Sync annotations to a database or backend service
Build analytics dashboards tracking feedback patterns
Create custom AI integrations (MCP servers, agent tools)

Props

onAnnotationAdd(annotation: Annotation) => void

Called when an annotation is created

onAnnotationDelete(annotation: Annotation) => void

Called when an annotation is deleted

onAnnotationUpdate(annotation: Annotation) => void

Called when an annotation comment is edited

onAnnotationsClear(annotations: Annotation[]) => void

Called when all annotations are cleared

onCopy(markdown: string) => void

Callback with the markdown output when copy is clicked

onSubmit(output: string, annotations: Annotation[]) => void

Called when "Send Annotations" is clicked

copyToClipboardbooleandefault: true

Set to false to prevent writing to clipboard (if handling via onCopy)

endpointstring

MCP server URL for syncing annotations

sessionIdstring

Pre-existing session ID to use

onSessionCreated(sessionId: string) => void

Called when a new session is created

webhookUrlstring

Webhook URL to receive annotation events

Basic usage

Receive annotation data directly in your code:

import { Agentation, Annotation } from "agentation";

function App() {
  const handleAnnotation = (annotation: Annotation) => {
    console.log(annotation.element, annotation.comment);
  };

  return (
    <>
      <YourApp />
      <Agentation onAnnotationAdd={handleAnnotation} />
    </>
  );
}

Annotation type

The Annotation object passed to callbacks. See Agentation Format for the full schema.

type Annotation = {
  // Required
  id: string;              // Unique identifier
  comment: string;         // User's annotation text
  elementPath: string;     // CSS selector path
  timestamp: number;       // Unix timestamp (ms)
  x: number;               // % of viewport width (0-100)
  y: number;               // px from document top
  element: string;         // Tag name ("button", "div")

  // Recommended
  url?: string;            // Page URL
  boundingBox?: {          // Element dimensions
    x: number;
    y: number;
    width: number;
    height: number;
  };

  // Context (varies by output format)
  reactComponents?: string;   // Component tree
  cssClasses?: string;
  computedStyles?: string;
  accessibility?: string;
  nearbyText?: string;
  selectedText?: string;      // If text was selected

  // Browser component fields
  isFixed?: boolean;       // Fixed-position element
  isMultiSelect?: boolean; // Created via drag selection
};

HTTP API

The agentation-mcp server provides a REST API for programmatic access:

Sessions

POST	/sessions	Create a new session
GET	/sessions	List all sessions
GET	/sessions/:id	Get session with annotations

Annotations

POST	/sessions/:id/annotations	Add annotation
GET	/annotations/:id	Get annotation
PATCH	/annotations/:id	Update annotation
DELETE	/annotations/:id	Delete annotation
POST	/annotations/:id/thread	Add thread message
GET	/sessions/:id/pending	Get pending annotations
GET	/pending	Get all pending annotations

Events (SSE)

GET	/sessions/:id/events	Session event stream
GET	/events	Global event stream (optionally filter with `?domain=...`)

Health

GET	/health	Health check
GET	/status	Server status

Real-Time Events

Subscribe to real-time events via Server-Sent Events:

# Session-level: events for a single page
curl -N http://localhost:4747/sessions/:id/events

# Global: events across ALL sessions
curl -N http://localhost:4747/events

# Filtered by domain: events for pages on a specific domain
curl -N "http://localhost:4747/events?domain=localhost:3001"

# Reconnect after disconnect (replay missed events)
curl -N -H "Last-Event-ID: 42" http://localhost:4747/sessions/:id/events

Event types

annotation.created — New annotation added
annotation.updated — Annotation modified (comment, status, etc.)
annotation.deleted — Annotation removed
session.created — New session started
session.updated — Session updated
session.closed — Session closed
action.requested — Agent action requested
thread.message — New message in annotation thread

Environment Variables

Variable	Description	Default
AGENTATION_STORE	Storage backend (`memory` or `sqlite`)	sqlite
AGENTATION_EVENT_RETENTION_DAYS	Days to keep events	7

Storage

By default, data is persisted to SQLite at ~/.agentation/store.db. To use in-memory storage:

AGENTATION_STORE=memory npx agentation-mcp server

Programmatic Usage

import { startHttpServer, startMcpServer } from 'agentation-mcp';

// Start HTTP server on port 4747
startHttpServer(4747);

// Start MCP server (connects via stdio)
await startMcpServer('http://localhost:4747');

See MCP Server for AI agent integration and available tools.