API Reference
Arivu's authenticated REST API for capture, Library, Search, learning sessions, Graph, notes, integrations, and operations.
The Go application serves its API under /api. This page is a route overview; the application repository at the pinned release is the source of truth for request and response fields.
Authentication Audiences
- Web uses HTTP-only cookies and CSRF protection for browser mutations.
- CLI uses bearer tokens from
/api/auth/cli/login. - Extension uses audience-scoped tokens issued through an authenticated web session.
Tokens cannot cross audience boundaries. Every owned query and mutation is scoped to the authenticated user.
Canonical Knowledge Routes
| Method | Endpoint | Purpose |
|---|---|---|
GET |
/api/library/items |
Cursor-based Library with content and derived scopes |
GET |
/api/search/items |
Bookmark and note retrieval |
GET |
/api/search/answer |
Cited answer from saved content |
POST |
/api/search/rebuild |
Rebuild the text index |
GET |
/api/knowledge-graph/v2 |
Bounded typed graph with focus and depth |
POST |
/api/feedback |
Search, relationship, or insight feedback |
GET / POST |
/api/learning |
List sessions or prepare fixed passages |
GET / DELETE |
/api/learning/{id} |
Read or delete an owned session |
POST |
/api/learning/{id}/generate |
Generate after provider consent |
POST |
/api/learning/{id}/submit |
Submit all quiz choices before reveal |
POST |
/api/learning/{id}/note |
Save an editable passage or AI-marked answer note |
Capture and Bookmarks
| Method | Endpoint | Purpose |
|---|---|---|
GET / POST |
/api/bookmarks |
List or create bookmarks |
GET / DELETE |
/api/bookmarks/{id} |
Read or delete a bookmark |
POST |
/api/bookmarks/preview |
Preview safe URL metadata |
POST |
/api/bookmarks/import |
Import bookmarks or restore JSON |
GET |
/api/bookmarks/export |
Export portable formats |
POST |
/api/bookmarks/backup |
Create a full JSON backup |
POST |
/api/media/import |
Import documents or transcripts as notes |
POST |
/api/calendar/import |
Retired; returns 410 Gone when authenticated |
Server-side URL preview and ingestion validate targets and redirects before fetching.
Evidence, Feeds, and Public Snapshots
| Route family | Purpose |
|---|---|
/api/artifacts/* |
Owner-authenticated artifact metadata and content |
/api/subscriptions/* |
Ongoing RSS and Atom subscription management |
/api/shares/* |
Create, list, update, revoke, or delete public snapshots |
/api/public/shares/* and /s/* |
Token-addressed public snapshot projections, feeds, and selected artifacts |
Public snapshot items are point-in-time copies, not live bookmark responses. Private fields are excluded, and authenticated share APIs can include only explicitly selected screenshot or PDF artifacts. Updating a share can deliberately replace its published membership under the same secret link.
Notes and Links
| Method | Endpoint | Purpose |
|---|---|---|
GET / POST |
/api/notes |
List or create notes |
PATCH / DELETE |
/api/notes/{id} |
Update or delete a note |
GET / POST |
/api/links |
List or create explicit links |
DELETE |
/api/links/{id} |
Delete an explicit link |
Retired task, reminder, planning, object, daily-note, and calendar APIs return 410 Gone when authenticated. The deterministic search-answer API remains available for compatibility, not as current chat.
Assistant, Organization, and Integrations
| Method | Endpoint | Purpose |
|---|---|---|
GET / POST |
/api/collections |
List or create collections |
GET |
/api/tags |
List tags |
GET |
/api/import-jobs |
List import jobs |
GET |
/api/import-jobs/{id} |
Inspect an import job |
POST |
/api/auth/extension-token |
Issue an extension token |
POST |
/api/extension/bookmarks |
Extension capture |
POST |
/api/extension/annotations |
Extension quote capture |
X connection and sync routes live under /api/auth/x/* and remain disabled unless configured.
Local Automation
CLI-audience /api/agent/* routes retain search, Library and saved-item reads,
Graph, legacy Insights reads, feedback, note creation, collections,
subscriptions, and share management. Task, reminder, and decision actions are
retired. Learning routes require the web audience; CLI tokens cannot use them.
This does not imply new top-level CLI commands.
Health and Errors
GET /api/health
Errors use a compact JSON body:
{
"detail": "Description of what went wrong"
}
Expect standard 400, 401, 403, 404, 409, 429, and 500 responses where applicable. Do not build a client from this overview alone; verify exact contracts against the application release you deploy.
Administration also exposes authenticated admin-only reads for durable processing failures and bounded retries for eligible failed bookmark jobs. Use the application UI or verify the exact admin route contract against the deployed release; failure history is retained when new work is queued.