API Reference
Overview of Arivu's authenticated REST API for owned capture, Library, Search, Graph, Insights, 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 |
GET |
/api/insights |
Deterministic evidence-backed patterns |
POST |
/api/feedback |
Search, relationship, or insight feedback |
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 |
Import calendar events as meeting objects |
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, Links, and Supporting Work
| Method | Endpoint | Purpose |
|---|---|---|
GET / POST |
/api/notes |
List or create notes |
PATCH / DELETE |
/api/notes/{id} |
Update or delete a note |
GET / PUT |
/api/daily-notes/{date} |
Read or save a daily note |
GET / POST |
/api/links |
List or create explicit links |
DELETE |
/api/links/{id} |
Delete an explicit link |
GET / POST |
/api/objects |
List or create knowledge objects |
GET / POST |
/api/action-items |
List or create tasks |
GET / POST |
/api/reminders |
List or create reminders |
Inbox, Focus, Review, and Board APIs remain available behind their compatibility contexts.
Assistant, Organization, and Integrations
| Method | Endpoint | Purpose |
|---|---|---|
GET / POST |
/api/assistant/actions |
List or propose reviewable actions |
POST |
/api/assistant/actions/{id}/approve |
Approve an action |
POST |
/api/assistant/actions/{id}/reject |
Reject an action |
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 provide scoped search, Library and saved-item reads, Graph, Insights, feedback, note creation, tasks, reminders, decisions, collections, subscriptions, and share management. They preserve CLI audience and ownership boundaries rather than exposing browser sessions. This API parity 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.