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/rest/

Authentication

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

curl -H "Api-Key: YOUR_API_KEY" http://localhost:8090/rest/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 "Api-Key: YOUR_KEY" \
  "http://localhost:8090/rest/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 "Api-Key: YOUR_KEY" \
  -H "Accept: text/event-stream" \
  http://localhost:8090/rest/events

Resources

Watchlist

GET /rest/watchlist

Returns all monitored series with their status and issue counts. Supports pagination.

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

Comics

GET /rest/comics

Search and filter across all comics in the library. Supports pagination and query parameters for filtering.

curl -H "Api-Key: YOUR_KEY" \
  "http://localhost:8090/rest/comics?limit=10"

Comic

GET    /rest/comic/{id}
PUT    /rest/comic/{id}
DELETE /rest/comic/{id}

Retrieve, update, or remove a specific comic series by its ComicVine ID.

# Get a specific series
curl -H "Api-Key: YOUR_KEY" http://localhost:8090/rest/comic/12345

# Update series settings
curl -H "Api-Key: YOUR_KEY" \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"status": "Paused"}' \
  http://localhost:8090/rest/comic/12345

# Remove a series from the watchlist
curl -H "Api-Key: YOUR_KEY" \
  -X DELETE \
  http://localhost:8090/rest/comic/12345

On this page