Upload a plugin jar

POST

/servers/{serverId}/plugins/upload

curl --request POST \
  --url https://example.com/api/v1/servers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/plugins/upload \
  --header 'Content-Type: application/octet-stream' \
  --cookie __Host-shardkeep_session=<__Host-shardkeep_session> \
  --data binary

Needs plugins.install; audited. Installs a plugin jar you supply (at most 64 MiB), for plugins that are private or not in the catalog. It must declare a plugin in paper-plugin.yml or plugin.yml; its name identifies it, so uploading another jar with the same name replaces it. Uploaded plugins are unverified: nothing vouches for them, and their compatibility is not checked.

Authorizations

• sessionCookie
• bearerToken

Parameters

Path Parameters

serverId

required

string format: uuid

Query Parameters

fileName

string

<= 255 characters

The jar’s file name, for display; only its last path element is kept.

Request Body^required

Media typeapplication/octet-stream

string format: binary

Responses

201

Installed; takes effect when the server next starts.

Media typeapplication/json

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

Example

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

413

The request body is too large.

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