API Reference

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

Authentication

Arivu supports two authentication modes:

• Browser sessions: HTTP-only cookies for the web app
• CLI sessions: Bearer tokens for terminal clients

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

CLI tokens are returned in the response body from /api/auth/cli/login and sent as Authorization: Bearer <token>.

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.

CLI Login

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

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

Returns bearer tokens and expiry metadata for terminal clients:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer",
  "access_token_expires_at": "2026-03-21T12:00:00+00:00",
  "refresh_token_expires_at": "2026-04-20T12:00:00+00:00",
  "user": {
    "id": "user_123",
    "email": "user@example.com",
    "name": "Example User"
  }
}

CLI Token Refresh

POST /api/auth/cli/refresh
Content-Type: application/json

{
  "refresh_token": "..."
}

Returns rotated bearer tokens for CLI consumers. Access tokens and invalid token types are rejected.

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

Bookmarks

Search

Knowledge Graph

Resurfacing

Analytics

Duplicates

Collections

Import/Export

Content Intelligence

X Integration

System

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

URL Preview

POST /api/bookmarks/preview
Authorization: Bearer <token>
Content-Type: application/json

{
  "url": "https://example.com/article"
}

Response:

{
  "url": "https://example.com/article",
  "title": "Article Title",
  "description": "Short page description",
  "domain": "example.com",
  "favicon": "https://example.com/favicon.ico",
  "thumbnail": null,
  "reading_time": 5
}

Preview uses the same server-side URL safety checks as bookmark ingestion, including DNS-aware private-address blocking and redirect revalidation.

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.