jack

Appearance

v0.1.0

jack management API​

Download OpenAPI Document

Operator-facing API on a separate listener from the public peer port. Drives the management UI: config, status, downloads, logs, catalog, and API keys.

Servers​

http://localhost:5226Default local management port (MANAGEMENT_PORT)

System​

Health and identity probes.

Operations​

GET/ping

Health check​

GET
/ping

Key-guarded probe: a 200 proves the key is valid and the management API is up.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

The management API is up and the key is valid

application/json
JSON
{
  
"ok": true
}

Samples​

Get the full config​

GET
/config

The loaded configuration with secrets redacted.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

List configured peers​

GET
/config/peers

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Add a peer​

POST
/config/peers

Persists a new peer and connects to it. ?force=true keeps the peer even if its handshake fails; it auto-retries lazily.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"name": "string",
  
"url": "string",
  
"apiKey": "string",
  
"headers": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

Success

application/json

Samples​

List configured servers​

GET
/config/servers

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Add a Radarr/Sonarr server​

POST
/config/servers

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"name": "string",
  
"url": "string",
  
"apiKey": "string",
  
"headers": {
  
  
"additionalProperties": "string"
  
},
  
"type": "string",
  
"source": true,
  
"destination": true,
  
"autoregister": {
  
  
"enable": true,
  
  
"priority": 0
  
}
}

Responses​

Success

application/json

Samples​

Get the jack block​

GET
/config/jack

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Update the jack block​

PATCH
/config/jack

Persists the new values; they take effect on next boot (no connectivity check).

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"internalUrl": "string",
  
"apiKey": "string",
  
"tmdbApiKey": "string",
  
"external": {
  
  
"instanceName": "string",
  
  
"url": "string",
  
  
"headers": null
  
}
}

Responses​

Success

application/json

Samples​

Get the downloads block​

GET
/config/downloads

The persisted downloads config, or null when downloads are not configured.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Update the downloads block​

PATCH
/config/downloads

Merges the given fields into the stored downloads config. unlinkImportedFiles applies immediately; the other values take effect on next boot.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"completedPath": "string",
  
"maxConcurrentDownloads": 0,
  
"maxDownloadAttempts": 0,
  
"retryBaseDelayMs": 0,
  
"retryMaxDelayMs": 0,
  
"idleTimeoutMs": 0,
  
"importPollIntervalMs": 0,
  
"maxManualImportAttempts": 0,
  
"manualImportBackoffBaseMs": 0,
  
"manualImportBackoffMaxMs": 0,
  
"unlinkImportedFiles": true
}

Responses​

Success

application/json

Samples​

Stream connector config​

GET
/config/stream

Server-Sent Events stream with an initial connector snapshot and immediate updates when connector state changes.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Live connector snapshots

text/event-stream

Samples​

Remove a peer​

DELETE
/config/peers/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required
Min Length
1

Responses​

Success

application/json

Samples​

Update a peer​

PATCH
/config/peers/{id}

Persists changes and reconnects. ?force=true keeps the peer even if its handshake fails.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required
Min Length
1

Request Body​

application/json
JSON
{
  
"name": "string",
  
"url": "string",
  
"apiKey": "string",
  
"headers": {
  
  
"additionalProperties": "string"
  
}
}

Responses​

Success

application/json

Samples​

Remove a server​

DELETE
/config/servers/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required
Min Length
1

Responses​

Success

application/json

Samples​

Update a server​

PATCH
/config/servers/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required
Min Length
1

Request Body​

application/json
JSON
{
  
"name": "string",
  
"url": "string",
  
"apiKey": "string",
  
"headers": {
  
  
"additionalProperties": "string"
  
},
  
"type": "string",
  
"source": true,
  
"destination": true,
  
"autoregister": {
  
  
"enable": true,
  
  
"priority": 0
  
}
}

Responses​

Success

application/json

Samples​

Remove external Jack access​

DELETE
/config/jack/external

Atomically removes only the external access profile.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Update external Jack access​

PATCH
/config/jack/external

Atomically replaces only the external access profile.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"instanceName": "string",
  
"url": "string",
  
"headers": null
}

Responses​

Success

application/json

Samples​

Status​

Connector and download overviews.

Operations​

GET/overviewGET/overview/streamGET/downloadsGET/downloads/stream

Connector overview​

GET
/overview

Configured servers and peers with their initialization state.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Overview of servers and peers

application/json

Samples​

Stream connector overview​

GET
/overview/stream

Server-Sent Events stream with an initial overview snapshot and immediate updates when connector or download state changes.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Live overview snapshots

text/event-stream

Samples​

List downloads​

GET
/downloads

All download records, in-flight and finished.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Download records

application/json

Samples​

Stream downloads​

GET
/downloads/stream

Server-Sent Events stream with an initial download snapshot and immediate updates after every persisted download change.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Live download snapshots

text/event-stream

Samples​

Downloads​

Manage individual download records by their numeric id.

Operations​

POST/downloads/{id}/cancelPOST/downloads/{id}/retryDELETE/downloads/{id}

Cancel a download​

POST
/downloads/{id}/cancel

Stops the active transfer and preserves its .part file for a later retry.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required

Responses​

The updated download record

application/json

Samples​

Retry a download​

POST
/downloads/{id}/retry

Repeats the last failed operation; transfers resume from the partial file, failed imports retry without re-downloading.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required

Responses​

The updated download record

application/json

Samples​

Delete a download​

DELETE
/downloads/{id}

Cancels any active work, removes the history row, and deletes its unshared partial or completed artifacts.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
string
Required

Responses​

The updated download record

application/json

Samples​

Logs​

Backfill and live-tail the process's own logs.

Operations​

GET/logsGET/logs/stream

Backfill recent logs​

GET
/logs

The last N log records, oldest to newest, with an optional minimum level.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Query Parameters

lines
Type
integer
Default
200
Minimum
1
Maximum
5000
level
Type
string
Valid values
"trace""debug""info""warn""error""fatal"

Responses​

Log records

application/json

Samples​

Live-tail logs​

GET
/logs/stream

Server-Sent Events stream; each event's data is one JSON log record. Emits a ping event every 15s to keep idle proxies from dropping the connection.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Query Parameters

level
Type
string
Valid values
"trace""debug""info""warn""error""fatal"

Responses​

SSE stream of log records

text/event-stream

Samples​

Catalog​

Aggregated peer catalog and TMDB-backed metadata for the UI.

Operations​

GET/catalog/tmdb/statusGET/catalog/tmdb/{mediaType}/{tmdbId}GET/catalog/request-optionsPOST/catalog/requestGET/catalog

TMDB integration status​

GET
/catalog/tmdb/status

Whether a TMDB API key is configured, so the UI knows if metadata lookups are available.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Get TMDB title metadata​

GET
/catalog/tmdb/{mediaType}/{tmdbId}

Per-title lookup the catalog grid calls once per visible card.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

mediaType*
Type
string
Required
Valid values
"movie""tv"
tmdbId*
Type
integer
Required
Minimum
-9007199254740991
Maximum
9007199254740991

Responses​

Success

application/json

Samples​

List request targets​

GET
/catalog/request-options

Destination servers (with root folders) a catalog item can be requested into.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Request a download​

POST
/catalog/request

Grabs a peer's catalog item into one of the local destination servers.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"peerId": "string",
  
"serverId": "string",
  
"mediaType": "string",
  
"tmdbId": 0,
  
"tvdbId": 0,
  
"rootFolderPath": "string"
}

Responses​

Success

application/json

Samples​

Get the aggregated catalog​

GET
/catalog

Everything available across all initialized peers.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

API keys​

Issue, list, and revoke the peer API keys this instance hands out.

Operations​

GET/api-keysPOST/api-keysGET/api-keys/{id}DELETE/api-keys/{id}PATCH/api-keys/{id}

List peer API keys​

GET
/api-keys

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Responses​

Success

application/json

Samples​

Create a peer API key​

POST
/api-keys

Issues a named, revocable, optionally expiring key. The plaintext key is only returned by this call.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"name": "string",
  
"description": "string",
  
"expiresAt": "string"
}

Responses​

Success

application/json

Samples​

Get a peer API key​

GET
/api-keys/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
integer
Required
Exclusive Minimum
0
Maximum
9007199254740991

Responses​

Success

application/json

Samples​

Revoke a peer API key​

DELETE
/api-keys/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
integer
Required
Exclusive Minimum
0
Maximum
9007199254740991

Responses​

Success

application/json

Samples​

Update a peer API key​

PATCH
/api-keys/{id}

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Parameters​

Path Parameters

id*
Type
integer
Required
Exclusive Minimum
0
Maximum
9007199254740991

Request Body​

application/json
JSON
{
  
"name": "string",
  
"description": "string",
  
"expiresAt": "string"
}

Responses​

Success

application/json

Samples​

Quick links​

Operations​

POST/quick-links

Generate a peer quick link​

POST
/quick-links

Resolves the configured external access profile, issues a fresh revocable API key, and returns a ready-to-share quick link. The link contains credentials and is returned only once.

Authorizations​

X-Management-Key

The JACK_MANAGEMENT_KEY the management listener was started with.

Type
API Key (header: X-Management-Key)

Request Body​

application/json
JSON
{
  
"peerName": "string",
  
"keyName": "string",
  
"keyDescription": "string",
  
"expiresAt": "string"
}

Responses​

Quick link generated

application/json
Powered by VitePress OpenAPI

Released under the GPL-3.0 License.