API Overview

Sensemaker exposes a GraphQL API for all data operations and a REST API for authentication and health checks.

Endpoints

Endpoint	Type	Purpose
/api/graphql	GraphQL	All data queries and mutations
/api/auth/login	REST POST	Email/password authentication
/api/auth/register	REST POST	User registration
/api/auth/google	REST POST	Google OAuth sign-in
/api/health	REST GET	Basic health check
/api/health/deep	REST GET	Full dependency health check
/api/swagger	Swagger UI	Interactive API documentation

Authentication

All API requests (except auth and health endpoints) require a JWT bearer token:

Authorization: Bearer <your-jwt-token>

Obtain a token by calling the login endpoint or through the login GraphQL mutation.

GraphQL Schema

The GraphQL API is code-first (auto-generated from NestJS decorators). Key types:

Queries

• viewer — Current authenticated user
• libraryItems — Paginated library with filters and search
• highlights — User's highlights with filtering
• tags — User's tags
• topics — User's topics

Mutations

• login / register — Authentication
• saveUrl — Save an article by URL
• createHighlight — Create a highlight on an article
• createTag / updateTag / deleteTag — Tag management
• subscribeToRssFeed — Subscribe to an RSS feed
• createNewsletterSubscription — Create a newsletter inbox

Rate Limiting

API requests are rate-limited to prevent abuse:

Endpoint Category	Limit
General API requests	100 requests/minute
Login / Register	5 requests/minute
Resend verification	3 requests per 5 minutes