Annotations API Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• packages/shared/src/types.ts
• extension/src/background/api-client.ts
• backend/lib/schema-validator.ts
• extension/src/background/index.ts
• backend/config/prompts.json

The Annotations API provides the backend infrastructure for generating, retrieving, and managing text annotations within the Oddity 1 platform. It facilitates communication between the Chrome extension and the Express-based backend to deliver AI-driven insights, handle user-generated notes, and track feedback loops. Sources: README.md:16-24, extension/src/background/api-client.ts:1-20

Core API Infrastructure

The API operates as an Express service deployable to Vercel, utilizing Supabase for authentication and data persistence. All endpoints, except health checks and adapter registry, require a valid Supabase access token passed in the Authorization header as a Bearer token. Sources: README.md:16-24, README.md:270-282

Authentication and Error Handling

The system implements specific error classes to handle authentication failures, rate limits, and usage quotas. The client automatically attempts to refresh the access token upon receiving a 401 Unauthorized response. Sources: extension/src/background/api-client.ts:10-53, extension/src/background/api-client.ts:93-113

Error Class	HTTP Status	Description
AuthError	401	Thrown when token refresh fails or credentials are invalid.
RateLimitError	429	Triggered by the server-side rate limiter (50/day free, 500/day pro).
UsageLimitError	403	Indicates the user has reached their monthly annotation quota.

Sources: extension/src/background/api-client.ts:10-40, README.md:284

Annotation Management Endpoints

AI Annotation Generation (POST /api/annotate)

This endpoint generates structured annotations using the OpenRouter LLM client. It supports Server-Sent Events (SSE) for real-time streaming of annotations as they are produced by the model. The backend validates incoming text against a maximum character limit and categorizes output into overview or depth modes based on system prompts. Sources: extension/src/background/api-client.ts:128-239, packages/shared/src/types.ts:121-128, backend/config/prompts.json:1-10

The diagram illustrates the request flow for AI annotations, highlighting the caching logic and streaming mechanism. Sources: extension/src/background/api-client.ts:153-239, README.md:300-302

User Annotation CRUD

Users can create manual annotations which are stored in the user_annotations table. Unlike AI annotations, these are tied to specific user profiles and support full lifecycle management (Create, Read, Update, Delete). Sources: extension/src/background/api-client.ts:261-300, README.md:297

Method	Path	Description
GET	/api/annotations	Fetches both cached AI annotations and user manual notes for a URL.
POST	/api/annotations	Saves a new manual annotation to the database.
PUT	/api/annotations/:id	Updates the content or label of an existing user annotation.
DELETE	/api/annotations/:id	Removes a user annotation from the database.

Sources: README.md:270-282, extension/src/background/api-client.ts:252-300

Feedback API (/api/annotations/feedback)

The feedback system allows users to interact with annotations through predefined reactions or text-based replies. Feedback is persisted and returned alongside annotations to facilitate collaborative or iterative reading. Sources: extension/src/background/api-client.ts:312-345, packages/shared/src/types.ts:101-107

Feedback Data Structures

export type FeedbackType = "thumbs_up" | "thumbs_down" | "reply";

export type AnnotationFeedback = {
  id: string;
  annotation_id: string;
  feedback_type: FeedbackType;
  reply_text: string | null;
  created_at: string;
};

Sources: packages/shared/src/types.ts:101-109

Data Validation and Schema

The backend utilizes zod for rigorous schema validation of annotation objects. This ensures that LLM-generated content adheres to the expected format before being transmitted to the extension or stored in the cache. The validator normalizes LLM output by converting spaces to underscores and forcing lowercase on type identifiers. Sources: backend/lib/schema-validator.ts:1-73

Annotation Data Model

Annotations are defined by their positioning (anchors) and their semantic role (types).

• Anchors: Uses TextQuoteSelector containing exact text, and optional prefix/suffix for disambiguation.
• Types: Categorized into OverviewLabel (e.g., core_claim, evidence) and DepthType (e.g., caveat, insight, fallacy).
• Content: Contains the primary note, along with optional fields like why_it_matters and question.

Sources: packages/shared/src/types.ts:49-90, backend/lib/schema-validator.ts:4-60

Conclusion

The Annotations API serves as the critical link between the client-side rendering engine and server-side intelligence. By combining high-performance streaming for AI generation with persistent storage for user notes and feedback, the API enables a rich, interactive reading experience. The implementation of strict schema validation and multi-tier error handling ensures system reliability across various web environments and user tiers. Sources: README.md:120-150, extension/src/background/api-client.ts:1-10