{
  "id": "user-defined",
  "title": "User-defined module requests",
  "url": "https://redis.io/docs/latest/operate/rs/8.0/references/rest-api/requests/modules/user-defined/",
  "summary": "Custom, user-defined Redis module requests",
  "content": "\n| Method | Path | Description |\n|--------|------|-------------|\n| [GET](#get-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | List custom module artifacts on a node |\n| [POST](#post-user-defined-module) | /v2/modules/user-defined | Upload custom module configuration |\n| [POST](#post-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | Upload a custom module artifact to a node |\n| [DELETE](#delete-user-defined-module) | /v2/modules/user-defined/\u003cuid\u003e | Delete a custom module configuration |\n| [DELETE](#delete-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts/\u003cmodule_name\u003e/\u003cversion\u003e | Delete a custom module artifact from a node |\n\n## List custom module artifacts {#get-local-user-defined-artifacts}\n\n```sh\nGET /v2/local/modules/user-defined/artifacts\n```\n\nReturns a list of all custom module artifacts on the local node.\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [view_cluster_modules](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#view_cluster_modules) | admin\u003cbr /\u003ecluster_member\u003cbr /\u003ecluster_viewer\u003cbr /\u003edb_member\u003cbr /\u003edb_viewer\u003cbr /\u003euser_manager |\n\n### Request {#get-local-artifacts-request}\n\n#### Example HTTP request\n\n```sh\nGET /v2/local/modules/user-defined/artifacts\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | \\*/\\* | Accepted media type |\n\n### Response {#get-local-artifacts-response}\n\nReturns a JSON array of custom module artifacts.\n\n#### Example JSON body\n\n```json\n[\n     {\n         \"module_name\": \"TestModule\",\n         \"version\": 123,\n         \"dependencies\": [\n             \"dep_1\",\n             \"dep_2\"\n         ]\n     }\n]\n```\n\n### Status codes {#get-local-artifacts-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, returns list of artifacts |\n\n## Upload custom module configuration {#post-user-defined-module}\n\n```sh\nPOST /v2/modules/user-defined\n```\n\nCreates a module object in the cluster configuration store (CCS). After calling this endpoint, you still need to upload the module's `.zip` file, which contains the `.so` and `module.json` files, to each node by calling [`POST /v2/local/modules/user-defined/artifacts`](#post-local-user-defined-artifacts) on each node.\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [manage_cluster_modules](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#manage_cluster_modules) | admin |\n\n### Request {#post-user-defined-request}\n\n#### Example HTTP request\n\n```sh\nPOST /v2/modules/user-defined\n```\n\n#### Example JSON body\n\n```json\n{\n     \"module_name\": \"TestModule\",\n     \"version\": 1,\n     \"semantic_version\": \"0.0.1\",\n     \"display_name\": \"test module\",\n     \"commands\": [\n         {\n             \"command_arity\": -1,\n             \"command_name\": \"json.arrtrim\",\n             \"first_key\": 1,\n             \"flags\": [\"write\"],\n             \"last_key\": 1,\n             \"step\": 1\n         }\n     ],\n     \"command_line_args\": \"\",\n     \"capabilities\": [\"list\", \"of\", \"capabilities\"],\n     \"min_redis_version\": \"2.1\"\n}\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\nThe request body is a JSON object that must contain the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| module_name | string | Name of the module |\n| version | integer | Module version number |\n| semantic_version | string | Module's semantic version |\n| display_name | string | Display name for the module |\n| commands | array of objects | List of commands provided by the module |\n| command_line_args | string | Command line arguments for the module |\n| capabilities | array of strings | List of capabilities supported by the module |\n| min_redis_version | string | Minimum Redis version required |\n\n### Response {#post-user-defined-response}\n\nReturns a [module object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/module).\n\n#### Example JSON body\n\n```json\n{\n    \"author\": \"author name\",\n    \"uid\": \"1952fcf9a5109fb59e61b1ad4d7e2d88\"\n    // additional fields...\n}\n```\n\n### Status codes {#post-user-defined-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module was created in the CCS. |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object, such as missing required fields or invalid values. |\n\n## Upload custom module artifact to a node {#post-local-user-defined-artifacts}\n\n```sh\nPOST /v2/local/modules/user-defined/artifacts\n```\n\nA local API to upload a custom module's artifact to the current node. You must call this API on each cluster node.\n\nThe module must be packaged as a `.zip` file containing:\n\n- **module.json**: A metadata file with module information including:\n  - `module_name`: The actual module name\n  - `version`: Numeric version\n  - `semantic_version`: Semantic version string (for example, \"1.0.0\")\n  - `min_redis_version`: Minimum compatible Redis version\n  - `commands`: List of commands the module provides\n  - `capabilities`: List of module capabilities\n\n- **Module binary**: The compiled `.so` file for the target platform\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [manage_cluster_modules](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#manage_cluster_modules) | admin |\n\n### Request {#post-local-artifacts-request}\n\n#### Example HTTP request\n\n```sh\nPOST /v2/local/modules/user-defined/artifacts\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | 127.0.0.1:9443 | Domain name |\n| Accept | \\*/\\* | Accepted media type |\n| Content-Length | 865 | Length of the request body in octets |\n| Expect | 100-continue | Requires particular server behaviors |\n| Content-Type | multipart/form-data; boundary=------------------------4751ac3b332ace13 | Media type of request/response body |\n\n### Response {#post-local-artifacts-response}\n\nReturns a status code to indicate upload success or failure.\n\n### Status codes {#post-local-artifacts-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, module artifact uploaded to local node |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Missing or bad artifact |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object artifact, such as bad metadata |\n\n## Delete custom module {#delete-user-defined-module}\n\n```sh\nDELETE /v2/modules/user-defined/{string: uid}\n```\n\nDelete a module object from the cluster configuration store (CCS). This REST API request does not delete the module artifact from the nodes, so you also need to call [`DELETE /v2/local/modules/user-defined/artifacts/\u003cmodule_name\u003e/\u003cversion\u003e`](#delete-local-user-defined-artifacts) on each node.\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [manage_cluster_modules](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#manage_cluster_modules) | admin |\n\n### Request {#delete-user-defined-request}\n\n#### Example HTTP request\n\n```sh\nDELETE /v2/modules/user-defined/1\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| uid | string | The module's unique ID |\n\n### Response {#delete-user-defined-response}\n\nReturns a status code to indicate module deletion success or failure.\n\n### Status codes {#delete-user-defined-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module is deleted. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |\n\n\n## Delete custom module artifact from a node{#delete-local-user-defined-artifacts}\n\n```sh\nDELETE /v2/local/modules/user-defined/artifacts/{string: module_name}/{int: version}\n```\n\nA local API to delete a custom module's artifact from the current node. You must call this API on each cluster node.\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [manage_cluster_modules](https://redis.io/docs/latest/operate/rs/references/rest-api/permissions#manage_cluster_modules) | admin |\n\n### Request {#delete-local-artifacts-request}\n\n#### Example HTTP request\n\n```sh\nDELETE /v2/local/modules/user-defined/artifacts/some-custom-module/123\n```\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | application/json | Accepted media type |\n\n#### URL parameters\n\n| Field | Type | Description |\n|-------|------|-------------|\n| module_name | string | The name of the module artifact to delete |\n| version | integer | The version of the module artifact to delete |\n\n### Response {#delete-local-artifacts-response}\n\nReturns a status code to indicate deletion success or failure.\n\n### Status codes {#delete-local-artifacts-status-codes}\n\n| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module artifact is deleted from the local node. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |\n| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-07-23T12:05:56-05:00"
}