{
  "id": "user-defined",
  "title": "User-defined module requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/modules/user-defined/",
  "summary": "Custom, user-defined Redis module requests",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-04-01T08:10:08-05:00",
  "page_type": "content",
  "content_hash": "390392a25f7a01fe8d7af5c3cdc5cd82578af2830d3f345446bab83def6caa89",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "| 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/<uid> | Delete a custom module configuration |\n| [DELETE](#delete-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts/<module_name>/<version> | Delete a custom module artifact from a node |"
    },
    {
      "id": "list-custom-module-artifacts-get-local-user-defined-artifacts",
      "title": "List custom module artifacts {#get-local-user-defined-artifacts}",
      "role": "content",
      "text": "[code example]\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]() | admin<br />cluster_member<br />cluster_viewer<br />db_member<br />db_viewer<br />user_manager |"
    },
    {
      "id": "request-get-local-artifacts-request",
      "title": "Request {#get-local-artifacts-request}",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Headers\n\n| Key | Value | Description |\n|-----|-------|-------------|\n| Host | cnm.cluster.fqdn | Domain name |\n| Accept | \\*/\\* | Accepted media type |"
    },
    {
      "id": "response-get-local-artifacts-response",
      "title": "Response {#get-local-artifacts-response}",
      "role": "returns",
      "text": "Returns a JSON array of custom module artifacts.\n\n#### Example JSON body\n\n[code example]"
    },
    {
      "id": "status-codes-get-local-artifacts-status-codes",
      "title": "Status codes {#get-local-artifacts-status-codes}",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, returns list of artifacts |"
    },
    {
      "id": "upload-custom-module-configuration-post-user-defined-module",
      "title": "Upload custom module configuration {#post-user-defined-module}",
      "role": "content",
      "text": "[code example]\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]() | admin |"
    },
    {
      "id": "request-post-user-defined-request",
      "title": "Request {#post-user-defined-request}",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\n\n#### Example JSON body\n\n[code example]\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 |"
    },
    {
      "id": "response-post-user-defined-response",
      "title": "Response {#post-user-defined-response}",
      "role": "returns",
      "text": "Returns a [module object]().\n\n#### Example JSON body\n\n[code example]"
    },
    {
      "id": "status-codes-post-user-defined-status-codes",
      "title": "Status codes {#post-user-defined-status-codes}",
      "role": "content",
      "text": "| 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. |"
    },
    {
      "id": "upload-custom-module-artifact-to-a-node-post-local-user-defined-artifacts",
      "title": "Upload custom module artifact to a node {#post-local-user-defined-artifacts}",
      "role": "content",
      "text": "[code example]\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]() | admin |"
    },
    {
      "id": "request-post-local-artifacts-request",
      "title": "Request {#post-local-artifacts-request}",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\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 |"
    },
    {
      "id": "response-post-local-artifacts-response",
      "title": "Response {#post-local-artifacts-response}",
      "role": "returns",
      "text": "Returns a status code to indicate upload success or failure."
    },
    {
      "id": "status-codes-post-local-artifacts-status-codes",
      "title": "Status codes {#post-local-artifacts-status-codes}",
      "role": "content",
      "text": "| 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 |"
    },
    {
      "id": "delete-custom-module-delete-user-defined-module",
      "title": "Delete custom module {#delete-user-defined-module}",
      "role": "content",
      "text": "[code example]\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/<module_name>/<version>`](#delete-local-user-defined-artifacts) on each node.\n\n#### Permissions\n\n| Permission name | Roles |\n|-----------------|-------|\n| [manage_cluster_modules]() | admin |"
    },
    {
      "id": "request-delete-user-defined-request",
      "title": "Request {#delete-user-defined-request}",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\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 |"
    },
    {
      "id": "response-delete-user-defined-response",
      "title": "Response {#delete-user-defined-response}",
      "role": "returns",
      "text": "Returns a status code to indicate module deletion success or failure."
    },
    {
      "id": "status-codes-delete-user-defined-status-codes",
      "title": "Status codes {#delete-user-defined-status-codes}",
      "role": "content",
      "text": "| 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. |"
    },
    {
      "id": "delete-custom-module-artifact-from-a-node-delete-local-user-defined-artifacts",
      "title": "Delete custom module artifact from a node{#delete-local-user-defined-artifacts}",
      "role": "content",
      "text": "[code example]\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]() | admin |"
    },
    {
      "id": "request-delete-local-artifacts-request",
      "title": "Request {#delete-local-artifacts-request}",
      "role": "content",
      "text": "#### Example HTTP request\n\n[code example]\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 |"
    },
    {
      "id": "response-delete-local-artifacts-response",
      "title": "Response {#delete-local-artifacts-response}",
      "role": "returns",
      "text": "Returns a status code to indicate deletion success or failure."
    },
    {
      "id": "status-codes-delete-local-artifacts-status-codes",
      "title": "Status codes {#delete-local-artifacts-status-codes}",
      "role": "content",
      "text": "| 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. |"
    }
  ],
  "examples": [
    {
      "id": "list-custom-module-artifacts-get-local-user-defined-artifacts-ex0",
      "language": "sh",
      "code": "GET /v2/local/modules/user-defined/artifacts",
      "section_id": "list-custom-module-artifacts-get-local-user-defined-artifacts"
    },
    {
      "id": "request-get-local-artifacts-request-ex0",
      "language": "sh",
      "code": "GET /v2/local/modules/user-defined/artifacts",
      "section_id": "request-get-local-artifacts-request"
    },
    {
      "id": "response-get-local-artifacts-response-ex0",
      "language": "json",
      "code": "[\n     {\n         \"module_name\": \"TestModule\",\n         \"version\": 123,\n         \"dependencies\": [\n             \"dep_1\",\n             \"dep_2\"\n         ]\n     }\n]",
      "section_id": "response-get-local-artifacts-response"
    },
    {
      "id": "upload-custom-module-configuration-post-user-defined-module-ex0",
      "language": "sh",
      "code": "POST /v2/modules/user-defined",
      "section_id": "upload-custom-module-configuration-post-user-defined-module"
    },
    {
      "id": "request-post-user-defined-request-ex0",
      "language": "sh",
      "code": "POST /v2/modules/user-defined",
      "section_id": "request-post-user-defined-request"
    },
    {
      "id": "request-post-user-defined-request-ex1",
      "language": "json",
      "code": "{\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}",
      "section_id": "request-post-user-defined-request"
    },
    {
      "id": "response-post-user-defined-response-ex0",
      "language": "json",
      "code": "{\n    \"author\": \"author name\",\n    \"uid\": \"1952fcf9a5109fb59e61b1ad4d7e2d88\"\n    // additional fields...\n}",
      "section_id": "response-post-user-defined-response"
    },
    {
      "id": "upload-custom-module-artifact-to-a-node-post-local-user-defined-artifacts-ex0",
      "language": "sh",
      "code": "POST /v2/local/modules/user-defined/artifacts",
      "section_id": "upload-custom-module-artifact-to-a-node-post-local-user-defined-artifacts"
    },
    {
      "id": "request-post-local-artifacts-request-ex0",
      "language": "sh",
      "code": "POST /v2/local/modules/user-defined/artifacts",
      "section_id": "request-post-local-artifacts-request"
    },
    {
      "id": "delete-custom-module-delete-user-defined-module-ex0",
      "language": "sh",
      "code": "DELETE /v2/modules/user-defined/{string: uid}",
      "section_id": "delete-custom-module-delete-user-defined-module"
    },
    {
      "id": "request-delete-user-defined-request-ex0",
      "language": "sh",
      "code": "DELETE /v2/modules/user-defined/1",
      "section_id": "request-delete-user-defined-request"
    },
    {
      "id": "delete-custom-module-artifact-from-a-node-delete-local-user-defined-artifacts-ex0",
      "language": "sh",
      "code": "DELETE /v2/local/modules/user-defined/artifacts/{string: module_name}/{int: version}",
      "section_id": "delete-custom-module-artifact-from-a-node-delete-local-user-defined-artifacts"
    },
    {
      "id": "request-delete-local-artifacts-request-ex0",
      "language": "sh",
      "code": "DELETE /v2/local/modules/user-defined/artifacts/some-custom-module/123",
      "section_id": "request-delete-local-artifacts-request"
    }
  ]
}