Search subtitles

GET

/api/v1/files/{id}/subtitle-results

curl --request GET \
  --url https://example.com/api/v1/files/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/subtitle-results \
  --cookie kivo_session=<kivo_session>

• The server itself, under its configured base path (such as `/kivo`).

Searches by the file’s hash and its work’s IDs, for any user who can see the file. Best first: those made for this exact file, then full subtitles before forced ones, then those not for the deaf and hard of hearing before SDH ones (SDH first when the user’s last subtitle choice for the series was SDH), then the most downloaded. Without an OpenSubtitles key on the server: 503 with code notConfigured.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

id

required

A UUIDv7.

string format: uuid

Query Parameters

language

Array<string>

BCP 47 tags, such as en. Default the user’s subtitle language, else the metadata language (the library’s, else the server’s).

Responses

200

Subtitle results, best first.

Media typeapplication/json

object

items

required

Array<object>

object

id

required

Opaque; pass it to addFileSubtitle.

string

language

required

A BCP 47 tag.

string

release

The release it was made for, such as Dune.2021.2160p.UHD.BluRay.

string

downloads

required

integer

hashMatch

required

Made for this exact file.

boolean

forced

required

Foreign parts only.

boolean

hearingImpaired

required

boolean

Example ^generated

{
  "items": [
    {
      "id": "example",
      "language": "example",
      "release": "example",
      "downloads": 1,
      "hashMatch": true,
      "forced": true,
      "hearingImpaired": true
    }
  ]
}

400

The request is malformed or a field is invalid (code invalidRequest).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

401

No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

403

Signed in, but this needs an admin (code forbidden); a same-origin request (code crossOrigin); or a device code that was denied (code denied).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

404

No such resource, or the caller may not see it (code notFound).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

default

A server-side failure: 500 (code internal, or transcodeFailed for a play’s media), or 503 for something unavailable (codes providerUnavailable and transcodeBusy, for now; notConfigured, until an admin configures it).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}