> ## Documentation Index > Fetch the complete documentation index at: https://aletyx.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # KIE Server REST API for KIE containers and business assets > Use the KIE Server REST API to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in jBPM without using the Business Central user interface. jBPM provides a KIE Server REST API that you can use to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in jBPM without using the Business Central user interface. This API support enables you to maintain your jBPM resources more efficiently and optimize your integration and development with jBPM. With the KIE Server REST API, you can perform the following actions: * Deploy or dispose KIE containers * Retrieve and update KIE container information * Return KIE Server status and basic information * Retrieve and update business asset information * Execute business assets (such as rules and processes) KIE Server REST API requests require the following components: **Authentication** The KIE Server REST API requires HTTP Basic authentication or token-based authentication for the user role `kie-server`. To view configured user roles for your jBPM distribution, navigate to `~/$SERVER_HOME/standalone/configuration/application-roles.properties` and `~/application-users.properties`. To add a user with the `kie-server` role, navigate to `~/$SERVER_HOME/bin` and run the following command: ```bash theme={null} $ ./bin/jboss-cli.sh --commands="embed-server --std-out=echo,/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity(identity=),/subsystem=elytron/filesystem-realm=ApplicationRealm:set-password(identity=, clear={password=''}),/subsystem=elytron/filesystem-realm=ApplicationRealm:add-identity-attribute(identity=, name=role, value=['kie-server'])" ``` For more information about user roles and jBPM installation options, see [Installing the KIE Server](/docs/kie-server/installation). **HTTP headers** The KIE Server REST API requires the following HTTP headers for API requests: * `Accept`: Data format accepted by your requesting client: * `application/json` (JSON) * `application/xml` (XML, for JAXB or XSTREAM) * `Content-Type`: Data format of your `POST` or `PUT` API request data: * `application/json` (JSON) * `application/xml` (XML, for JAXB or XSTREAM) * `X-KIE-ContentType`: Required header for `application/xml` XSTREAM API requests and responses: * `XSTREAM` **HTTP methods** The KIE Server REST API supports the following HTTP methods for API requests: * `GET`: Retrieves specified information from a specified resource endpoint * `POST`: Updates a resource or resource instance * `PUT`: Updates or creates a resource or resource instance * `DELETE`: Deletes a resource or resource instance **Base URL** The base URL for KIE Server REST API requests is `http://SERVER:PORT/kie-server/services/rest/`, such as `http://localhost:8080/kie-server/services/rest/`. **Endpoints** KIE Server REST API endpoints, such as `/server/containers/{containerId}` for a specified KIE container, are the URIs that you append to the KIE Server REST API base URL to access the corresponding resource or type of resource in jBPM. **Example request URL for `/server/containers/{containerId}` endpoint** `http://localhost:8080/kie-server/services/rest/server/containers/MyContainer` **Request parameters and request data** Many KIE Server REST API requests require specific parameters in the request URL path to identify or filter specific resources and to perform specific actions. You can append URL parameters to the endpoint in the format `?=&=`. **Example GET request URL with parameters** `http://localhost:8080/kie-server/services/rest/server/containers?groupId=com.redhat&artifactId=Project1&version=1.0&status=STARTED` HTTP `POST` and `PUT` requests may additionally require a request body or file with data to accompany the request. **Example POST request URL and JSON request body data** `http://localhost:8080/kie-server/services/rest/server/containers/MyContainer/release-id` ```json theme={null} { "release-id": { "artifact-id": "Project1", "group-id": "com.redhat", "version": "1.1" } } ``` ## Sending requests with the KIE Server REST API using a REST client or curl utility The KIE Server REST API enables you to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in jBPM without using the Business Central user interface. You can send KIE Server REST API requests using any REST client or curl utility. **Prerequisites** * KIE Server is installed and running. * You have `kie-server` user role access to KIE Server. **Procedure** 1. Identify the relevant [API endpoint](#supported-kie-server-rest-api-endpoints) to which you want to send a request, such as `[GET] /server/containers` to retrieve KIE containers from KIE Server. 2. In a REST client or curl utility, enter the following components for a `GET` request to `/server/containers`. Adjust any request details according to your use case. For REST client: * **Authentication**: Enter the user name and password of the KIE Server user with the `kie-server` role. * **HTTP Headers**: Set the following header: * `Accept`: `application/json` * **HTTP method**: Set to `GET`. * **URL**: Enter the KIE Server REST API base URL and endpoint, such as `http://localhost:8080/kie-server/services/rest/server/containers`. For curl utility: * `-u`: Enter the user name and password of the KIE Server user with the `kie-server` role. * `-H`: Set the following header: * `Accept`: `application/json` * `-X`: Set to `GET`. * **URL**: Enter the KIE Server REST API base URL and endpoint, such as `http://localhost:8080/kie-server/services/rest/server/containers`. ```bash theme={null} curl -u 'baAdmin:password@1' -H "Accept: application/json" -X GET "http://localhost:8080/kie-server/services/rest/server/containers" ``` 3. Execute the request and review the KIE Server response. Example server response (JSON): ```json theme={null} { "type": "SUCCESS", "msg": "List of created containers", "result": { "kie-containers": { "kie-container": [ { "container-id": "itorders_1.0.0-SNAPSHOT", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "DISPOSED", "poll-interval": null }, "config-items": [], "container-alias": "itorders" } ] } } } ``` 4. For this example, copy or note the project `group-id`, `artifact-id`, and `version` (GAV) data from one of the deployed KIE containers returned in the response. 5. In your REST client or curl utility, send another API request with the following components for a `PUT` request to `/server/containers/{containerId}` to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case. For REST client: * **Authentication**: Enter the user name and password of the KIE Server user with the `kie-server` role. * **HTTP Headers**: Set the following headers: * `Accept`: `application/json` * `Content-Type`: `application/json` When you add `fields=not_null` to `Content-Type`, the null fields are excluded from the REST API response. * **HTTP method**: Set to `PUT`. * **URL**: Enter the KIE Server REST API base URL and endpoint, such as `http://localhost:8080/kie-server/services/rest/server/containers/MyContainer`. * **Request body**: Add a JSON request body with the configuration items for the new KIE container: ```json theme={null} { "config-items": [ { "itemName": "RuntimeStrategy", "itemValue": "SINGLETON", "itemType": "java.lang.String" }, { "itemName": "MergeMode", "itemValue": "MERGE_COLLECTIONS", "itemType": "java.lang.String" }, { "itemName": "KBase", "itemValue": "", "itemType": "java.lang.String" }, { "itemName": "KSession", "itemValue": "", "itemType": "java.lang.String" } ], "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "scanner": { "poll-interval": "5000", "status": "STARTED" } } ``` For curl utility: * `-u`: Enter the user name and password of the KIE Server user with the `kie-server` role. * `-H`: Set the following headers: * `Accept`: `application/json` * `Content-Type`: `application/json` When you add `fields=not_null` to `Content-Type`, the null fields are excluded from the REST API response. * `-X`: Set to `PUT`. * **URL**: Enter the KIE Server REST API base URL and endpoint, such as `http://localhost:8080/kie-server/services/rest/server/containers/MyContainer`. * `-d`: Add a JSON request body or file (`@file.json`) with the configuration items for the new KIE container: ```bash theme={null} curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d "{ \"config-items\": [ { \"itemName\": \"RuntimeStrategy\", \"itemValue\": \"SINGLETON\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"MergeMode\", \"itemValue\": \"MERGE_COLLECTIONS\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KBase\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" }, { \"itemName\": \"KSession\", \"itemValue\": \"\", \"itemType\": \"java.lang.String\" } ], \"release-id\": { \"group-id\": \"itorders\", \"artifact-id\": \"itorders\", \"version\": \"1.0.0-SNAPSHOT\" }, \"scanner\": { \"poll-interval\": \"5000\", \"status\": \"STARTED\" }}" ``` ```bash theme={null} curl -u 'baAdmin:password@1' -H "Accept: application/json" -H "Content-Type: application/json" -X PUT "http://localhost:8080/kie-server/services/rest/server/containers/MyContainer" -d @my-container-configs.json ``` 6. Execute the request and review the KIE Server response. Example server response (JSON): ```json theme={null} { "type": "SUCCESS", "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.", "result": { "kie-container": { "container-id": "MyContainer", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "STARTED", "poll-interval": 5000 }, "config-items": [], "messages": [ { "severity": "INFO", "timestamp": { "java.util.Date": 1540584717937 }, "content": [ "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT." ] } ], "container-alias": null } } } ``` If you encounter request errors, review the returned error code messages and adjust your request accordingly. **REST API requests for process instances** For REST API requests that send complex data objects to the process instance endpoint `/server/containers/{containerId}/processes/{processId}/instances`, ensure that you include either the fully qualified class name (such as `com.myspace.Person`) or the simple class name (such as `Person`) in the request body. The class name is required for the request body to be mapped to the correct business object in jBPM. If you exclude the class name from the request, KIE Server does not unmarshall the object to the expected type. ```json Correct request body for process instance theme={null} { "id": 4, "lease": { "com.myspace.restcall.LeaseModel": { "annualRent": 109608, "isAutoApproved": false } } } ``` ```json Incorrect request body for process instance theme={null} { "id": 4, "lease": { "annualRent": 109608, "isAutoApproved": false } } ``` ## Sending requests with the KIE Server REST API using the Swagger interface The KIE Server REST API supports a Swagger web interface that you can use instead of a standalone REST client or curl utility to interact with your KIE containers and business assets (such as business rules, processes, and solvers) in jBPM without using the Business Central user interface. By default, the Swagger web interface for KIE Server is enabled by the `org.kie.swagger.server.ext.disabled=false` system property. To disable the Swagger web interface in KIE Server, set this system property to `true`. **Prerequisites** * KIE Server is installed and running. * You have `kie-server` user role access to KIE Server. **Procedure** 1. In a web browser, navigate to `http://SERVER:PORT/kie-server/docs`, such as `http://localhost:8080/kie-server/docs`, and log in with the user name and password of the KIE Server user with the `kie-server` role. 2. In the Swagger page, select the relevant API endpoint to which you want to send a request, such as **KIE Server and KIE containers** → **\[GET] /server/containers** to retrieve KIE containers from KIE Server. 3. Click **Try it out** and provide any optional parameters by which you want to filter results, if needed. 4. In the **Response content type** drop-down menu, select the desired format of the server response, such as **application/json** for JSON format. 5. Click **Execute** and review the KIE Server response. Example server response (JSON): ```json theme={null} { "type": "SUCCESS", "msg": "List of created containers", "result": { "kie-containers": { "kie-container": [ { "container-id": "itorders_1.0.0-SNAPSHOT", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "DISPOSED", "poll-interval": null }, "config-items": [], "container-alias": "itorders" } ] } } } ``` 6. For this example, copy or note the project `group-id`, `artifact-id`, and `version` (GAV) data from one of the deployed KIE containers returned in the response. 7. In the Swagger page, navigate to the **KIE Server and KIE containers** → **\[PUT] `/server/containers/{containerId}`** endpoint to send another request to deploy a new KIE container with the copied project GAV data. Adjust any request details according to your use case. 8. Click **Try it out** and enter the following components for the request: * **containerId**: Enter the ID of the new KIE container, such as `MyContainer`. * **body**: Set the **Parameter content type** to the desired request body format, such as **application/json** for JSON format, and add a request body with the configuration items for the new KIE container: ```json theme={null} { "config-items": [ { "itemName": "RuntimeStrategy", "itemValue": "SINGLETON", "itemType": "java.lang.String" }, { "itemName": "MergeMode", "itemValue": "MERGE_COLLECTIONS", "itemType": "java.lang.String" }, { "itemName": "KBase", "itemValue": "", "itemType": "java.lang.String" }, { "itemName": "KSession", "itemValue": "", "itemType": "java.lang.String" } ], "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "scanner": { "poll-interval": "5000", "status": "STARTED" } } ``` 9. In the **Response content type** drop-down menu, select the desired format of the server response, such as **application/json** for JSON format. 10. Click **Execute** and review the KIE Server response. Example server response (JSON): ```json theme={null} { "type": "SUCCESS", "msg": "Container MyContainer successfully deployed with module itorders:itorders:1.0.0-SNAPSHOT.", "result": { "kie-container": { "container-id": "MyContainer", "release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "resolved-release-id": { "group-id": "itorders", "artifact-id": "itorders", "version": "1.0.0-SNAPSHOT" }, "status": "STARTED", "scanner": { "status": "STARTED", "poll-interval": 5000 }, "config-items": [], "messages": [ { "severity": "INFO", "timestamp": { "java.util.Date": 1540584717937 }, "content": [ "Container MyContainer successfully created with module itorders:itorders:1.0.0-SNAPSHOT." ] } ], "container-alias": null } } } ``` If you encounter request errors, review the returned error code messages and adjust your request accordingly. **REST API requests for process instances** For REST API requests that send complex data objects to the process instance endpoint `/server/containers/{containerId}/processes/{processId}/instances`, ensure that you include either the fully qualified class name (such as `com.myspace.Person`) or the simple class name (such as `Person`) in the request body. The class name is required for the request body to be mapped to the correct business object in jBPM. If you exclude the class name from the request, KIE Server does not unmarshall the object to the expected type. ```json Correct request body for process instance theme={null} { "id": 4, "lease": { "com.myspace.restcall.LeaseModel": { "annualRent": 109608, "isAutoApproved": false } } } ``` ```json Incorrect request body for process instance theme={null} { "id": 4, "lease": { "annualRent": 109608, "isAutoApproved": false } } ``` ## Supported KIE Server REST API endpoints The KIE Server REST API provides endpoints for the following types of resources in jBPM: * KIE Server and KIE containers * KIE session assets (for runtime commands) * DMN assets * Planning solvers * Processes * Process images * Process and task forms * Tasks * Cases * Documents * Jobs * Queries for processes, tasks, and cases * Custom queries The KIE Server REST API base URL is `http://SERVER:PORT/kie-server/services/rest/`. All requests require HTTP Basic authentication or token-based authentication for the `kie-server` user role. For the full list of KIE Server REST API endpoints and descriptions, use one of the following resources: * [Execution Server REST API](http://jbpm.org/learn/documentation.html) on the jBPM Documentation page (static) * Swagger UI for the KIE Server REST API at `http://SERVER:PORT/kie-server/docs` (dynamic, requires running KIE Server) By default, the Swagger web interface for KIE Server is enabled by the `org.kie.swagger.server.ext.disabled=false` system property. To disable the Swagger web interface in KIE Server, set this system property to `true`. For API access to process images, the system property `` must be configured for your jBPM project in `$SERVER_HOME/standalone/deployments/business-central.war/org.kie.workbench.KIEWebapp/profiles/jbpm.xml`. This property is set to `true` by default. If the API is not working with process images, set it to `true` in the file, restart your KIE Server, modify the relevant process and save it, and then build and deploy your project. This property enables SVG images to be stored so that they can be retrieved by the KIE Server REST API. ### Custom queries You can use custom query endpoints to create and access custom queries in jBPM. Custom queries can request any data from the jBPM database. A number of custom queries are included in jBPM. You can use these queries to access complete lists of process instances and user tasks. When running a custom query, you must provide the name of a *query mapper* in the `mapper` parameter. A mapper maps SQL query results into objects for a JSON response. You can implement your own query result mappers or use the mappers provided with jBPM. The query mappers in jBPM are similar to other object-relational mapping (ORM) providers, such as Hibernate, which maps tables to entities. For example, if a custom query returns process instance data, you can use the `org.jbpm.kie.services.impl.query.mapper.ProcessInstanceQueryMapper` mapper, also registered as `ProcessInstances`. If a custom query returns human task data, you can use the `org.jbpm.kie.services.impl.query.mapper.UserTaskInstanceQueryMapper` mapper, also registered as `UserTasks`. You can also use other mappers that provide additional information. For a list of query mappers that are included in jBPM, see the [GitHub repository](https://github.com/kiegroup/jbpm/tree/7.67.2.Final/jbpm-services/jbpm-kie-services/src/main/java/org/jbpm/kie/services/impl/query/mapper). {/* TODO: Review this */}