Skip to content
Shardkeep

Install a catalog plugin

POST
/servers/{serverId}/plugins
curl --request POST \
  --url https://example.com/api/v1/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/plugins \
  --header 'Content-Type: application/json' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data '{ "pluginId": "example", "versionId": "example", "force": false }'

Needs plugins.install; audited. Installs a catalog plugin (the given version, or the newest compatible one) and the required dependencies it does not have yet, each at its newest compatible version. Jars are downloaded from their publisher and verified against the catalog first; nothing changes if any of that fails. The server must be READY and run Paper or Purpur. A version not marked for the server’s Minecraft version (plugin_incompatible), or a required dependency missing from the catalog (plugin_dependency_missing), is refused unless force is set; a version for other software (plugin_wrong_platform) always is.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
serverId
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
pluginId
required
string
>= 3 characters <= 200 characters
versionId

The newest compatible version when absent.

string
<= 200 characters
force
boolean

Responses

Section titled “Responses”

201

Section titled “201”

Installed; takes effect when the server next starts.

Media typeapplication/json
object
changed
required

The plugins installed or updated, the requested one first.

Array<object>
object
id
required

The installation’s ID.

string format: uuid
pluginId
required

The catalog plugin ID, or upload:<name> for an uploaded jar.

string
name
required
string
source
required
string
Allowed values: CATALOG UPLOAD
version
required
string
catalogVersionId
string
verified
required

False for uploads.

boolean
compatibilityConfirmed
required

False when it was installed with force, or is an upload.

boolean
dependency
required

True when it was installed because another plugin requires it.

boolean
requiredBy
required

Plugin IDs of installed plugins that require this one.

Array<string>
denied

Set when the catalog’s denylist names this version.

object
reason
required
string
link
string
updateAvailable

The newest catalog version compatible with the server, when it is newer than this one.

object
versionId
required
string
version
required
string
installedAt
required
string format: date-time
updatedAt
required
string format: date-time
missingDependencies
required

Required dependencies that are not in the catalog (only with force).

Array<string>
Example
{
  "changed": [
    {
      "pluginId": "modrinth:Vebnzrzj",
      "source": "CATALOG"
    }
  ]
}

400

Section titled “400”

The request is invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

401

Section titled “401”

Not signed in, or the credentials are invalid.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

403

Section titled “403”

Signed in, but not allowed.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

404

Section titled “404”

Not found, or not visible to you.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

409

Section titled “409”

Clashes with existing data or state.

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

502

Section titled “502”

A jar could not be downloaded from its publisher, or did not match its published checksum (download_failed).

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

503

Section titled “503”

The catalog has not been synced yet (catalog_unavailable).

Media typeapplication/problem+json

An RFC 9457 problem with a machine-readable code.

object
type
required
string
title
required
string
status
required
integer
detail
string
code
required

Stable machine-readable error code.

string
Example
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "code": "conflict"
}

Shardkeep is free software under the AGPL-3.0. Minecraft is a trademark of Mojang AB; Shardkeep is not affiliated with or endorsed by Mojang or Microsoft.