scholarr/docs/reference/api.md

title	sidebar_position
API Contract	2

API Contract

Envelope Invariant

All API responses under /api/v1 use one of these envelopes:

Success

{
  "data": "...",
  "meta": {
    "request_id": "..."
  }
}

Error

{
  "error": {
    "code": "...",
    "message": "...",
    "details": "..."
  },
  "meta": {
    "request_id": "..."
  }
}

meta.request_id is present on both success and error responses.

Binary Assets

Binary media assets are served outside /api/v1:

GET /scholar-images/{scholar_profile_id}/upload

DTO Structure

Scholarr uses strictly typed Pydantic V2 models serialized through OpenAPI v3 via FastAPI.

• PublicationListItem exposes a .display_identifier property that resolves the highest-confidence identifier regardless of backend origin, rather than a hardcoded .doi.
• Frontend TypeScript types are compiled from the OpenAPI spec to ensure type safety across the stack.

Endpoints

Auth

Method	Path	Description
POST	/api/v1/auth/login	Login (rate-limited sliding window)
GET	/api/v1/auth/me	Current session user
GET	/api/v1/auth/csrf	Bootstrap CSRF token
POST	/api/v1/auth/change-password	Change password
POST	/api/v1/auth/logout	Logout

Scholars

Method	Path	Description
GET	/api/v1/scholars	List tracked scholars
POST	/api/v1/scholars	Create scholar (auto-enqueue, metadata hydration)
GET	/api/v1/scholars/search	Search author candidates by name
PATCH	/api/v1/scholars/{id}/toggle	Toggle enabled status
DELETE	/api/v1/scholars/{id}	Delete scholar
PUT	/api/v1/scholars/{id}/image/url	Update image URL
POST	/api/v1/scholars/{id}/image/upload	Upload image
DELETE	/api/v1/scholars/{id}/image	Clear image customization

Scholar Portability

Method	Path	Description
GET	/api/v1/scholars/export	Export tracked scholars and publication link state
POST	/api/v1/scholars/import	Import scholars with global publication deduplication

The export payload includes scholar metadata, tracked publication data, and link state (read/unread, favorites). Import preserves global deduplication.

Publications

Method	Path	Description
GET	/api/v1/publications	List publications (filtered, paginated)
POST	/api/v1/publications/mark-all-read	Mark all as read
POST	/api/v1/publications/mark-read	Mark selected as read
POST	/api/v1/publications/{id}/retry-pdf	Retry PDF resolution
POST	/api/v1/publications/{id}/favorite	Toggle favorite

Publication Modes

GET /api/v1/publications supports a mode parameter:

Mode	Description
all	All publications
unread	Publications with is_read=false
latest	Publications first seen in the latest completed run

mode=new is accepted as a compatibility alias for latest.

Pagination

Query parameters: page, page_size (with backward-compatible limit/offset support).

Response pagination fields:

{
  "page": 1,
  "page_size": 20,
  "has_prev": false,
  "has_next": true,
  "total_count": 142
}

Publication Payload Fields

Field	Description
pub_url	Canonical scholar detail URL
doi	Normalized DOI
pdf_url	Resolved open-access PDF URL (when available)
display_identifier	Highest-confidence identifier regardless of source

Runs

Method	Path	Description
GET	/api/v1/runs	List runs with safety state
GET	/api/v1/runs/{run_id}	Run detail with scholar results
POST	/api/v1/runs/{run_id}/cancel	Cancel active run
POST	/api/v1/runs/manual	Trigger manual run (idempotent, safety-checked)
GET	/api/v1/runs/queue/items	List queue items
POST	/api/v1/runs/queue/{id}/retry	Retry queue item
POST	/api/v1/runs/queue/{id}/drop	Drop queue item
DELETE	/api/v1/runs/queue/{id}	Clear queue item
GET	/api/v1/runs/{run_id}/stream	Stream run events (SSE)

Settings

Method	Path	Description
GET	/api/v1/settings	Get user settings (with cooldown expiry check)
PUT	/api/v1/settings	Update settings (interval, delay, nav, API keys)

Admin - User Management

Method	Path	Description
GET	/api/v1/admin/users	List all users
POST	/api/v1/admin/users	Create user
PATCH	/api/v1/admin/users/{id}/active	Set user active status
POST	/api/v1/admin/users/{id}/reset-password	Reset password

Admin - Database Operations

Method	Path	Description
GET	/api/v1/admin/db/integrity	Get integrity report
GET	/api/v1/admin/db/repair-jobs	List repair jobs
GET	/api/v1/admin/db/pdf-queue	List PDF queue
POST	/api/v1/admin/db/pdf-queue/{id}/requeue	Requeue single PDF
POST	/api/v1/admin/db/pdf-queue/requeue-all	Bulk requeue missing PDFs
POST	/api/v1/admin/db/repairs/publication-links	Trigger link repair
POST	/api/v1/admin/db/repairs/publication-near-duplicates	Trigger dedup repair
POST	/api/v1/admin/db/drop-all-publications	Drop all publications (destructive)