REST API

The REST API is the primary programmatic interface to Comicarr. It uses standard HTTP methods and JSON bodies. Most routes require a JWT session cookie; a small set of library browse GETs accept X-Api-Key.

Base URL

http://localhost:8090/api/

Authentication

See Authentication for session cookies, API keys, and CSRF.

# Session (full API)
curl -b cookies.txt http://localhost:8090/api/series

# API key (library browse only)
curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/watchlist

Response format

Responses are not wrapped in a single global envelope. Shapes vary by endpoint:

List endpoints often return domain keys plus pagination metadata, e.g. {"comics": [...], "pagination": {...}}
Errors typically use FastAPI-style {"detail": "..."} with the appropriate HTTP status code
Some handlers return plain lists or status objects

Always check the HTTP status code and the endpoint’s documented fields.

Pagination

Where pagination is supported, clients commonly send limit / offset (or page-style query params depending on the route). Defaults and response field names vary — inspect the JSON for pagination, total, or similar.

Event stream (SSE)

Real-time updates use server-sent events:

GET /api/events/stream

This endpoint requires a session cookie (not API key). Example:

curl -N -b cookies.txt \
  -H "Accept: text/event-stream" \
  http://localhost:8090/api/events/stream

Full event names and payload fields: Server-Sent Events.

Resources

Series & library (session)

GET    /api/series
GET    /api/series/{comic_id}
POST   /api/series
DELETE /api/series/{comic_id}
PUT    /api/series/{comic_id}/pause
PUT    /api/series/{comic_id}/resume
POST   /api/series/{comic_id}/refresh
POST   /api/series/bulk-delete
POST   /api/series/bulk-pause
POST   /api/series/bulk-resume
PUT    /api/series/issues/{issue_id}/queue
PUT    /api/series/issues/{issue_id}/unqueue
GET    /api/wanted

Library browse (API key)

GET /api/watchlist
GET /api/comics
GET /api/comic/{comic_id}
GET /api/comic/{comic_id}/issues
GET /api/comic/{comic_id}/issue/{issue_id}

Import

GET    /api/import
POST   /api/import/match
PATCH  /api/import/{imp_id}
POST   /api/import/ignore
DELETE /api/import
POST   /api/import/refresh
POST   /api/import/comic/scan
GET    /api/import/comic/progress
POST   /api/import/comic/confirm
POST   /api/import/manga/scan
GET    /api/import/manga/progress
POST   /api/import/manga/confirm

Search

POST /api/search/comics
POST /api/search/manga
POST /api/search/add
POST /api/search/add-manga
POST /api/search/force
POST /api/search/rss/force
GET  /api/search/providers

Downloads

GET    /api/downloads/history
DELETE /api/downloads/history
POST   /api/downloads/process
POST   /api/downloads/process/issue
GET    /api/downloads/queue
POST   /api/downloads/{item_id}/requeue
POST   /api/downloads/ddl
DELETE /api/downloads/{item_id}
GET    /api/downloads/file/{issue_id}

Metadata

POST /api/metadata/search
POST /api/metadata/search/manga
GET  /api/metadata/comic/{comic_id}
GET  /api/metadata/issue/{issue_id}
GET  /api/metadata/art/{comic_id}
GET  /api/metadata/image-proxy
GET  /api/metadata/series-image/{series_id}
POST /api/metadata/metatag
POST /api/metadata/metatag/bulk
POST /api/metadata/metatag/group

Story arcs & reading lists

GET    /api/storyarcs
GET    /api/storyarcs/{arc_id}
DELETE /api/storyarcs/{arc_id}
POST   /api/storyarcs/generate
POST   /api/storyarcs/generate/save
POST   /api/storyarcs/{arc_id}/want-all
POST   /api/storyarcs/{arc_id}/refresh
GET    /api/readlist
POST   /api/readlist
DELETE /api/readlist/{issue_id}
DELETE /api/readlist
GET    /api/upcoming

Weekly & dashboard

GET /api/weekly
GET /api/dashboard

AI

GET  /api/ai/status
POST /api/ai/test
GET  /api/ai/activity
POST /api/ai/chat/stream
GET  /api/ai/suggestions

System & config

POST /api/auth/login
POST /api/auth/logout
GET  /api/auth/check-session
GET  /api/auth/check-setup
POST /api/auth/setup
GET  /api/events/stream
GET  /api/config
PUT  /api/config
POST /api/config/api-key/regenerate
PUT  /api/config/providers
GET  /api/system/version
GET  /api/system/logs
GET  /api/system/jobs
GET  /api/system/diagnostics
POST /api/system/migration/preview
POST /api/system/migration/start
GET  /api/system/migration/progress
POST /api/system/shutdown
POST /api/system/restart

OPDS

OPDS is a separate catalog under /opds (not under /api). See the Reading (OPDS) guide.

On this page