REST API

The REST API is the primary programmatic interface to Comicarr. It uses standard HTTP methods, JSON request/response bodies, and header-based authentication.

Base URL

http://localhost:8090/api/

Authentication

Include your API key in the X-Api-Key header on every request:

curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:8090/api/watchlist

See Authentication for all auth methods.

Response Format

All responses follow a consistent envelope:

{
  "success": true,
  "data": {
    "results": [...],
    "total": 142,
    "limit": 25,
    "offset": 0,
    "has_more": true
  }
}

{
  "success": false,
  "error": {
    "code": 404,
    "message": "Comic not found"
  }
}

Pagination

List endpoints support limit and offset query parameters:

Parameter	Description	Default
`limit`	Maximum number of results to return	`25`
`offset`	Number of results to skip	`0`

The response includes pagination metadata:

Field	Description
`total`	Total number of matching records
`limit`	Limit used for this request
`offset`	Offset used for this request
`has_more`	`true` if more results exist beyond this page

Example -- fetch the second page of 10 results:

curl -H "X-Api-Key: YOUR_KEY" \
  "http://localhost:8090/api/watchlist?limit=10&offset=10"

Event Stream

The REST API supports server-sent events (SSE) for real-time updates. Connect to the event stream endpoint to receive push notifications for downloads, post-processing, and library changes.

curl -H "X-Api-Key: YOUR_KEY" \
  -H "Accept: text/event-stream" \
  http://localhost:8090/api/events/stream

Resources

Series

Manage monitored series in your library.

GET    /api/series                          # List all series
GET    /api/series/{comic_id}               # Get series detail
POST   /api/series                          # Add series
DELETE /api/series/{comic_id}               # Remove series
PUT    /api/series/{comic_id}/pause         # Pause series
PUT    /api/series/{comic_id}/resume        # Resume series
POST   /api/series/{comic_id}/refresh       # Refresh metadata
PUT    /api/series/issues/{issue_id}/queue   # Queue issue for download
PUT    /api/series/issues/{issue_id}/unqueue # Unqueue issue

curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/series

curl -H "X-Api-Key: YOUR_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"comic_id": 12345}' \
  http://localhost:8090/api/series

curl -H "X-Api-Key: YOUR_KEY" \
  -X PUT \
  http://localhost:8090/api/series/12345/pause

Watchlist & Browse

Read-only endpoints for browsing the library. Authenticated via API key.

GET /api/wanted                     # Get wanted issues
GET /api/watchlist                   # Get watchlist
GET /api/comics                      # Browse all comics
GET /api/comic/{comic_id}           # Get comic detail
GET /api/comic/{comic_id}/issues    # Get issues for a comic

curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/watchlist

Search

Search comic and manga providers, add results, and trigger forced searches.

POST /api/search/comics      # Search comic providers
POST /api/search/manga       # Search manga providers
POST /api/search/add         # Add from search results
POST /api/search/add-manga   # Add manga from search
POST /api/search/force       # Force search
POST /api/search/rss/force   # Force RSS check
GET  /api/search/providers   # List search providers

curl -H "X-Api-Key: YOUR_KEY" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"query": "Batman"}' \
  http://localhost:8090/api/search/comics

curl -H "X-Api-Key: YOUR_KEY" \
  -X POST \
  http://localhost:8090/api/search/force

Downloads

View download history and queue, trigger post-processing, and manage individual items.

GET    /api/downloads/history              # Download history
DELETE /api/downloads/history              # Clear history
POST   /api/downloads/process             # Trigger post-processing
GET    /api/downloads/queue               # Current download queue
POST   /api/downloads/{item_id}/requeue   # Requeue failed item
POST   /api/downloads/ddl                 # Queue DDL download
DELETE /api/downloads/{item_id}           # Cancel download

curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/downloads/queue

Metadata

Search and retrieve metadata, and tag files.

POST /api/metadata/search              # Search metadata
GET  /api/metadata/comic/{comic_id}    # Get comic metadata
GET  /api/metadata/issue/{issue_id}    # Get issue metadata
POST /api/metadata/metatag             # Tag a file

curl -H "X-Api-Key: YOUR_KEY" \
  http://localhost:8090/api/metadata/comic/12345

Story Arcs

Manage story arcs and their issues.

GET    /api/storyarcs                       # List story arcs
GET    /api/storyarcs/{arc_id}              # Get arc detail
DELETE /api/storyarcs/{arc_id}              # Delete arc
POST   /api/storyarcs/{arc_id}/want-all    # Want all arc issues
POST   /api/storyarcs/{arc_id}/refresh     # Refresh arc

curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/storyarcs

System

Authentication, configuration, and server management.

POST /api/auth/login          # Login
POST /api/auth/logout         # Logout
GET  /api/events/stream       # SSE event stream
GET  /api/config              # Get configuration
PUT  /api/config              # Update configuration
GET  /api/system/version      # Get version
GET  /api/system/logs         # Get logs
POST /api/system/shutdown     # Shutdown
POST /api/system/restart      # Restart

curl -H "X-Api-Key: YOUR_KEY" http://localhost:8090/api/system/version

On this page