Arivu
Getting Started Getting Started
Deployment Self-Hosting Arivu Environment Variables
Integrations X Bookmarks Integration Browser Extension Setup
Features Knowledge Graph Collections & Tags Analytics & Insights Import & Export Resurfacing & Rediscovery
Reference API Reference Keyboard Shortcuts
Reference

API Reference

Overview of the Arivu REST API — authentication, endpoints, and request/response patterns for all 35+ endpoints.

The Arivu API is a RESTful API built with FastAPI. All endpoints are served under the /api prefix.

Authentication

Arivu uses HTTP-only cookie-based authentication:

  • access_token — Valid for 60 minutes
  • refresh_token — Valid for 30 days

Tokens are set as HTTP-only cookies on login. The frontend sends cookies automatically via withCredentials: true. No manual Authorization header is needed.

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securepassword"
}

Response sets access_token and refresh_token cookies.

Token Refresh

POST /api/auth/refresh

Uses the refresh_token cookie to issue a new access_token.

Current User

GET /api/auth/me

Returns the authenticated user’s profile. Used by the frontend on page load to verify session.

API Categories

Authentication

Method Endpoint Auth Description
POST /api/auth/signup No Create account
POST /api/auth/login No Login
POST /api/auth/logout Yes Logout (clears cookies)
POST /api/auth/refresh Cookie Refresh access token
GET /api/auth/me Yes Current user profile
PUT /api/auth/profile Yes Update profile
POST /api/auth/change-password Yes Change password
POST /api/auth/forgot-password No Request password reset
POST /api/auth/reset-password No Reset password with token
GET /api/auth/extension-token Yes Get extension auth token

Bookmarks

Method Endpoint Description
GET /api/bookmarks List bookmarks (paginated, filtered)
POST /api/bookmarks Create bookmark
GET /api/bookmarks/{id} Get bookmark details
PUT /api/bookmarks/{id} Update bookmark
DELETE /api/bookmarks/{id} Delete bookmark
POST /api/bookmarks/import Import bookmarks from file
GET /api/bookmarks/export Export all bookmarks
GET /api/bookmarks/aged Get stale/unread bookmarks
Method Endpoint Description
GET /api/search Hybrid keyword + semantic search

Knowledge Graph

Method Endpoint Description
GET /api/knowledge-graph Full graph data
GET /api/knowledge-graph/stats Graph statistics
POST /api/knowledge-graph/rebuild Trigger rebuild

Resurfacing

Method Endpoint Description
GET /api/resurfacing/suggestions Resurfacing suggestions
POST /api/resurfacing/snooze/{id} Snooze a bookmark
POST /api/resurfacing/archive/{id} Archive from resurfacing

Analytics

Method Endpoint Description
GET /api/analytics/reading-stats Reading statistics
GET /api/analytics/topic-analysis Topic analysis
GET /api/analytics/patterns Activity patterns
GET /api/analytics/ai-insights AI-generated insights
GET /api/analytics/summary Comprehensive summary

Duplicates

Method Endpoint Description
GET /api/duplicates Detect duplicate bookmarks
POST /api/duplicates/merge Merge duplicate bookmarks
POST /api/duplicates/dismiss Dismiss a duplicate pair

Collections

Method Endpoint Description
GET /api/collections List collections
POST /api/collections Create collection
PUT /api/collections/{id} Update collection
DELETE /api/collections/{id} Delete collection
POST /api/collections/{id}/bookmarks Add bookmark
DELETE /api/collections/{id}/bookmarks/{bid} Remove bookmark

Import/Export

Method Endpoint Description
POST /api/bookmarks/import Import from file
GET /api/bookmarks/export Export all bookmarks
GET /api/import-jobs List import jobs
GET /api/import-jobs/{id} Import job status

Content Intelligence

Method Endpoint Description
GET /api/content-intelligence/{id} Content quality evaluation

X Integration

Method Endpoint Description
GET /api/x/auth-url Get OAuth authorization URL
POST /api/x/callback Handle OAuth callback
GET /api/x/status Connection and sync status
POST /api/x/sync Trigger bookmark sync
POST /api/x/disconnect Disconnect X account

System

Method Endpoint Description
GET /api/health Health check
GET /api/feature-flags Active feature flags

Common Patterns

Pagination

List endpoints accept skip and limit query parameters:

GET /api/bookmarks?skip=0&limit=20

Filtering

Bookmarks support filtering by tag, collection, and search query:

GET /api/bookmarks?tag=python&collection_id=abc123&q=machine+learning

Error Responses

All errors follow a consistent format:

{
  "detail": "Description of what went wrong"
}

Common status codes: 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 500 (server error).

Interactive API Docs

When running locally, FastAPI provides interactive API documentation at:

  • Swagger UI: http://localhost:8001/docs
  • ReDoc: http://localhost:8001/redoc

These are auto-generated from the backend code and always reflect the current API surface.

← Resurfacing & Rediscovery Keyboard Shortcuts →