Search

Endpoints for searching releases across configured indexers.

Authentication

All search endpoints require authentication.

Endpoint	Auth Level
GET `/api/search`	requireAuth
POST `/api/download/grab`	requireAuth

Search releases

Performs a multi-indexer search for releases matching the query parameters.

GET /api/search

Request parameters

Parameter	Type	Required	Description
query	string	No	Search query string
type	string	No	Media type (movie, tv)
tmdbId	integer	No	TMDB ID to search for
tvdbId	integer	No	TVDB ID for TV series
seriesId	string	No	Series UUID to search for
movieId	string	No	Movie UUID to search for
seasonNumber	integer	No	Season number (TV only)
episodeNumber	integer	No	Episode number (TV only)
indexers	string	No	Comma-separated indexer IDs
categories	string	No	Comma-separated category IDs
minSeeders	integer	No	Minimum seeders (torrent)
maxAge	integer	No	Maximum age in days
limit	integer	No	Maximum results (default: 100)

Query types

Type	Required parameters	Description
`manual`	query	Free-form search
`movie`	movieId or tmdbId	Search for specific movie
`tv`	seriesId or tmdbId	Search for TV series
`episode`	seriesId, seasonNumber, episodeNumber	Search specific episode

Response codes

Code	Description
200	Success
400	Invalid parameters
401	Authentication required
404	Movie/series not found

Response schema

{
  "releases": [
    {
      "guid": "string",
      "title": "string",
      "size": "integer",
      "indexer": "string",
      "indexerId": "string",
      "publishDate": "string",
      "downloadUrl": "string",
      "infoUrl": "string",
      "category": ["string"],
      "seeders": "integer",
      "leechers": "integer",
      "protocol": "string",
      "quality": {
        "quality": "string",
        "resolution": "string",
        "source": "string",
        "modifier": "string"
      },
      "qualityScore": "integer",
      "customFormatScore": "integer",
      "rejections": ["string"],
      "approved": "boolean",
      "releaseGroup": "string",
      "language": "string",
      "mappedMovie": {
        "id": "string",
        "title": "string",
        "year": "integer"
      },
      "mappedSeries": {
        "id": "string",
        "title": "string"
      },
      "mappedEpisode": {
        "seasonNumber": "integer",
        "episodeNumber": "integer"
      }
    }
  ],
  "indexerResults": [
    {
      "indexerId": "string",
      "indexerName": "string",
      "resultCount": "integer",
      "status": "string",
      "errorMessage": "string"
    }
  ],
  "totalResults": "integer",
  "searchDuration": "number",
  "searchTime": "string"
}

Release quality fields

Field	Description	Values
`quality`	Quality name	Bluray-1080p, WEBDL-720p, HDTV-1080p, etc.
`resolution`	Video resolution	480p, 720p, 1080p, 2160p
`source`	Media source	Bluray, WEB, HDTV, DVD
`modifier`	Quality modifier	REMUX, x265, HDR, DV

Rejection reasons

Reason	Description
`Unknown movie`	Cannot map to library movie
`Unknown series`	Cannot map to library series
`Unknown episode`	Cannot map to specific episode
`Release rejected`	Does not meet quality requirements
`Custom format cut-off unmet`	Below custom format score threshold
`Release is blacklisted`	In blacklist

Example request

curl -H "x-api-key: cinephage_your_key_here" \
  "http://localhost:3000/api/search?movieId=550e8400-e29b-41d4-a716-446655440000&limit=10"

Example response

{
  "releases": [
    {
      "guid": "Indexer1-12345",
      "title": "Inception.2010.1080p.BluRay.x264-Group",
      "size": 10485760000,
      "indexer": "Indexer1",
      "indexerId": "a10e8400-e29b-41d4-a716-446655440010",
      "publishDate": "2024-01-15T08:00:00Z",
      "downloadUrl": "https://example.com/download/12345",
      "infoUrl": "https://example.com/details/12345",
      "category": ["Movies", "HD"],
      "seeders": 150,
      "leechers": 12,
      "protocol": "torrent",
      "quality": {
        "quality": "Bluray-1080p",
        "resolution": "1080p",
        "source": "Bluray",
        "modifier": "x264"
      },
      "qualityScore": 100,
      "customFormatScore": 1500,
      "rejections": [],
      "approved": true,
      "releaseGroup": "Group",
      "language": "English",
      "mappedMovie": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Inception",
        "year": 2010
      }
    }
  ],
  "indexerResults": [
    {
      "indexerId": "a10e8400-e29b-41d4-a716-446655440010",
      "indexerName": "Indexer1",
      "resultCount": 15,
      "status": "success",
      "errorMessage": null
    }
  ],
  "totalResults": 15,
  "searchDuration": 2.345,
  "searchTime": "2024-01-15T10:30:00Z"
}

Grab release

Downloads a specific release to the download client.

POST /api/download/grab

Request body schema

Field	Type	Required	Description
guid	string	Yes	Release GUID from search
indexerId	string	Yes	Indexer ID
movieId	string	No	Movie UUID (for movies)
seriesId	string	No	Series UUID (for TV)
seasonNumber	integer	No	Season number (TV)
episodeIds	array	No	Episode UUIDs (TV)

Response codes

Code	Description
201	Grab successful
400	Invalid request
401	Authentication required
404	Release or media not found
409	Release already grabbed

Response schema

{
  "success": "boolean",
  "downloadId": "string",
  "queueId": "string",
  "title": "string",
  "message": "string"
}

Example request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: cinephage_your_key_here" \
  -d '{
    "guid": "Indexer1-12345",
    "indexerId": "a10e8400-e29b-41d4-a716-446655440010",
    "movieId": "550e8400-e29b-41d4-a716-446655440000"
  }' \
  http://localhost:3000/api/download/grab

Example response

{
  "success": true,
  "downloadId": "dl_550e8400-e29b-41d4-a716-446655440020",
  "queueId": "q_550e8400-e29b-41d4-a716-446655440021",
  "title": "Inception.2010.1080p.BluRay.x264-Group",
  "message": "Release sent to download client"
}

Scoring and ranking

Quality score

Quality scores range from 0 to 100, with higher values indicating better quality.

Quality	Score
Bluray-2160p	100
WEBDL-2160p	90
Bluray-1080p	80
WEBDL-1080p	70
HDTV-1080p	60
Bluray-720p	50
WEBDL-720p	40
HDTV-720p	30
DVD	20
SDTV	10

Custom format score

Custom format scores are calculated based on matching conditions:

Field	Description
`customFormatScore`	Total score from all matching custom formats
`rejections`	Reasons if score is below cutoff

Release approval

A release is approved when:

It maps to a library movie/episode
It meets quality requirements
It meets custom format score cutoff
It is not blacklisted

Search providers

Cinephage supports searching across multiple indexer types:

Type	Protocols	Description
Usenet	NZB	Newznab-compatible indexers
Torrent	Magnet, Torrent file	Torznab and RSS indexers
IPTV	M3U	Live TV sources

Authentication​

Search releases​

Request parameters​

Query types​

Response codes​

Response schema​

Release quality fields​

Rejection reasons​

Example request​

Example response​

Grab release​

Request body schema​

Response codes​

Response schema​

Example request​

Example response​

Scoring and ranking​

Quality score​

Custom format score​

Release approval​

Search providers​

See Also​

Authentication

Search releases

Request parameters

Query types

Response codes

Response schema

Release quality fields

Rejection reasons

Example request

Example response

Grab release

Request body schema

Response codes

Response schema

Example request

Example response

Scoring and ranking

Quality score

Custom format score

Release approval

Search providers

See Also