Update a plugin or change its version

PUT

/servers/{serverId}/plugins/{pluginInstallId}

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

Needs plugins.update; audited. Moves a catalog plugin to the given version, or to the newest compatible one, with the same rules and dependency handling as installing. Uploaded plugins are replaced by uploading a new jar.

Authorizations

• sessionCookie
• bearerToken

Parameters

Path Parameters

serverId

required

string format: uuid

pluginInstallId

required

string format: uuid

Request Body^required

Media typeapplication/json

object

versionId

The newest compatible version when absent.

string

<= 200 characters

force

boolean

Responses

200

Updated; 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

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

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

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

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

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

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

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"
}