Solr Package Manager API

Use the SearchStax API to add custom Solr JAR files with Solr Package Manager.

Use Package Manager as the preferred workflow for adding or upgrading custom JARs on Managed Search deployments where Package Manager is enabled. Instead of adding a custom JAR directory to solrconfig.xml and restarting Solr after each upload, you upload JAR files to Filestore, register package versions, and reference the package name from your configset.

Solr Package Manager uses Solr Filestore. Filestore stores and distributes JAR files across Solr nodes in a deployment. Package Manager references those files, assigns package names and versions, and makes the classes in those files available to Solr.

Package Manager helps when you upgrade custom JAR files over time. After your configset references a package-prefixed class name, you can upload a new JAR and register a package version without changing the configset, reloading collections, or restarting Solr.

During migration, the Custom JARs mechanism and Package Manager can operate at the same time. This lets you move custom classes to Package Manager incrementally. The Custom JARs workflow remains available for legacy deployments and migration cases.

For the legacy custom JAR upload and restart workflow, see Solr Custom JARs API.

Prerequisites

Before you start, you need:

• A SearchStax Managed Search deployment running Solr 9 or later
• A Premium Managed Search plan, such as Gold or higher
• A SearchStax user with Technical Contact access or higher
• Package Manager enabled on the deployment, or an eligible deployment where Package Manager can be enabled
• A SearchStax API token
• The SearchStax account name
• The deployment UID
• A JAR file to upload
• Permission to update the relevant Solr configsets
• Permission to reload affected Solr collections after configset changes

API Base URL

The examples in this article use the following base URL:

https://app.searchstax.com/api/rest/v2

The examples use the following variables:

Authenticate

Request an authentication token from the SearchStax API:

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "username": "<username>",
    "password": "<password>",
    "tfa_token": "<tfa_token>"
  }' \
  https://app.searchstax.com/api/rest/v2/obtain-auth-token/

The tfa_token field is optional unless your SearchStax account requires two-factor authentication.

The response includes a token:

{
  "token": "<token>"
}

For the remaining requests, include the token in the Authorization header:

Authorization: Token <token>

Step 1: Check Package Manager Availability

Package Manager is available for Solr 9 deployments on eligible Managed Search plans. New Solr 9 deployments created in July 2026 or later have Package Manager enabled by default. Existing Solr 9 deployments created before July 2026 may need Package Manager enabled before you use package-managed JAR files.

List existing packages to review the packages registered with the deployment:

curl -s \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/

Successful response: 200 OK.

Example response:

{
  "result": {
    "znodeVersion": 0,
    "packages": {
      "my-package": [
        {
          "package": "my-package",
          "version": "1.0.0",
          "files": [
            "/my-plugin-1.0.0.jar"
          ]
        }
      ]
    }
  }
}

If Package Manager isn’t enabled on your deployment, use the enable endpoint before uploading package-managed JAR files.

Step 2: Enable Package Manager, If Needed

If Package Manager isn’t enabled on an eligible deployment, use the enable endpoint before you use package-managed JAR files:

curl -s -X POST \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/enable/

Successful response: 200 OK.

Don’t include a request body unless SearchStax provides one for your deployment or workflow.

Note: For deployments created before July 2026, contact SearchStax Support if you can’t enable Package Manager from your account.

Enabling Package Manager may trigger a rolling restart of the deployment.

Step 3: Upload a JAR File to Filestore

Upload the JAR file to Solr Filestore:

curl -s -X POST \
  -H "Authorization: Token <token>" \
  -F "file=@./my-plugin-1.0.0.jar" \
  -F "checksum=<sha512_checksum>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/files/

The checksum field is optional. Use this field to provide the SHA-512 checksum of the JAR file.

When you upload a JAR through the SearchStax API, SearchStax signs the JAR and uploads the signed JAR to Filestore. Solr validates the signature before accepting the file.

Request Fields

Successful response: 201 Created.

Example response:

{
  "file": "/my-plugin-1.0.0.jar",
  "responseHeader": {
    "status": 0,
    "QTime": 67
  }
}

If the same file metadata already exists, the response can include a message similar to the following:

{
  "file": "/my-plugin-1.0.0.jar",
  "message": "File with same metadata exists ",
  "responseHeader": {
    "status": 0,
    "QTime": 13
  }
}

Step 4: Create a Package Version

After the JAR is available in Filestore, register it as a Solr package version:

curl -s -X POST \
  -H "Authorization: Token <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": {
      "package": "my-package",
      "version": "1.0.0",
      "files": [
        "/my-plugin-1.0.0.jar"
      ]
    }
  }' \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/

Request Fields

Successful response: 200 OK.

Example response:

{
  "responseHeader": {
    "status": 0,
    "QTime": 59
  }
}

If the package version already exists, the response can include a Solr 400 error:

{
  "responseHeader": {
    "status": 400,
    "QTime": 8
  },
  "error": {
    "msg": "Error executing command, errors: [...]",
    "code": 400
  }
}

Note: Solr uses lexicographic ordering, not semantic version ordering, to determine the latest package version. For example, Solr considers 1.9.0 newer than 1.11.0. Choose version labels carefully so the latest intended version sorts correctly.

Step 5: Update Configset Class References

Update the relevant Solr configset files so Solr references the package-prefixed class name.

Before Package Manager, custom classes use a fully qualified class name.

class="com.example.solr.MyClass"

With Package Manager, prefix the class name with the package name:

class="my-package:com.example.solr.MyClass"

For example, the following request handler:

<requestHandler name="/example" class="com.example.solr.MyClass" />

becomes the following:

<requestHandler name="/example" class="my-package:com.example.solr.MyClass" />

Upload the modified configset using your normal configset management workflow.

Step 6: Reload Affected Collections

Reload each Solr collection that uses the updated configset.

The reload applies the initial configset changes without requiring a full deployment restart.

Use your normal collection reload workflow. This might be a SearchStax workflow, a Solr API workflow, or a process that you coordinate with SearchStax Support.

Update a Package to a New JAR Version

To update a package, upload the new JAR file and create a package version with the same package name.

For example, upload my-plugin-1.1.0.jar, and then register a new version of my-package:

curl -s -X POST \
  -H "Authorization: Token <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "add": {
      "package": "my-package",
      "version": "1.1.0",
      "files": [
        "/my-plugin-1.1.0.jar"
      ]
    }
  }' \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/

After the configset uses the package-prefixed class name, future package version changes don’t require another configset class-name change, collection reload, or Solr restart. Solr uses the latest package version automatically.

Note: Because Solr uses lexicographic ordering to determine the latest package version, confirm that the new version sorts after the previous version.

Manage Existing Files

List Files

List files in Solr Filestore:

curl -s \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/files/

Successful response: 200 OK.

Example response:

{
  "files": {
    "/": [
      {
        "name": "my-plugin-1.0.0.jar",
        "size": 262,
        "timestamp": 1712345678901,
        "sig": [
          "<signature>"
        ],
        "sha512": "<sha512_checksum>"
      },
      {
        "name": "_trusted_",
        "dir": true
      }
    ]
  },
  "responseHeader": {
    "status": 0,
    "QTime": 5
  }
}

Get File Metadata

Retrieve metadata for a specific file.

The <filename> path parameter can’t contain /.

curl -s \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/files/<filename>/

Successful response: 200 OK.

Example response:

{
  "files": {
    "/my-plugin-1.0.0.jar": {
      "name": "my-plugin-1.0.0.jar",
      "size": 262,
      "timestamp": 1712345678901,
      "sig": [
        "<signature>"
      ],
      "sha512": "<sha512_checksum>"
    }
  },
  "responseHeader": {
    "status": 0,
    "QTime": 5
  }
}

Download a File

Download a file from Solr Filestore.

The <filename> path parameter can’t contain /.

curl -L \
  -H "Authorization: Token <token>" \
  -o my-plugin-1.0.0.jar \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/files/<filename>/download/

Successful response: 200 OK.

Response body: Binary file content. The response is the file itself, not a JSON object.

Delete a File

Delete a file from Solr Filestore.

The <filename> path parameter can’t contain /.

A file can’t be part of any package when you delete it. Delete the package version that references the file before deleting the file.

curl -s -X DELETE \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/files/<filename>/

Successful response: 200 OK.

The response body can include a Solr response header.

{
  "responseHeader": {
    "status": 0,
    "QTime": 18
  }
}

If the file is still referenced by a package, the response can include a Solr 400 error:

{
  "responseHeader": {
    "status": 400,
    "QTime": 11
  },
  "error": {
    "msg": "jar in use, can't delete",
    "code": 400
  }
}

Manage Existing Packages

List Packages

List packages registered with Solr Package Manager:

curl -s \
  -H "Authorization: Token <token>" \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/

Successful response: 200 OK.

Example response:

{
  "result": {
    "znodeVersion": 2,
    "packages": {
      "my-package": [
        {
          "package": "my-package",
          "version": "1.0.0",
          "files": [
            "/my-plugin-1.0.0.jar"
          ]
        },
        {
          "package": "my-package",
          "version": "1.1.0",
          "files": [
            "/my-plugin-1.1.0.jar"
          ]
        }
      ]
    }
  }
}

Delete a Package Version

Use the delete package command to delete a package version:

curl -s -X POST \
  -H "Authorization: Token <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "delete": {
      "package": "my-package",
      "version": "1.0.0"
    }
  }' \
  https://app.searchstax.com/api/rest/v2/account/<account_name>/deployment/<uid>/solr/package-manager/

Request Fields

Successful response: 200 OK.

Example response:

{
  "responseHeader": {
    "status": 0,
    "QTime": 10
  }
}

Note: The package delete command uses the same POST /package-manager/ endpoint as package creation.

Endpoint Reference

Package Manager Endpoints

File Endpoints

Request Body Reference

Upload File Request

Add Package Version Request

{
  "add": {
    "package": "my-package",
    "version": "1.0.0",
    "files": [
      "/my-plugin-1.0.0.jar"
    ]
  }
}

Delete Package Version Request

{
  "delete": {
    "package": "my-package",
    "version": "1.0.0"
  }
}