REST Endpoints

What are REST Endpoints?

Use Groovy scripts to define REST endpoints allowing you to integrate with external systems and exchange data. An endpoint is a URL that runs a script. ScriptRunner REST Endpoints allows you to create custom endpoints to suit your needs. 

How to use REST Endpoints

REST endpoints are configured programmatically. You can define REST endpoints in ScriptRunner to:

  • Use in dashboard gadgets.

  • Receive information from external systems.

  • Plug gaps in the official REST API.

  • Allow all your XHRs to proxy through to other systems.

For example, you want to show a custom popup dialog to your users if they click a button in your Jira instance. To do this, you could create a rest endpoint that returns HTML to build the custom dialog and then use that with a custom web item to display the dialog to your users when they click a custom button within your Jira instance.

Alternatively, you may want to create a REST endpoint to receive information from an external system. For example, you have an external system you use to log all new cars in your showroom. You want to be able to call the endpoint and have ScriptRunner add a new custom field option for each new car added to the external system. 

The REST Endpoint page in ScriptRunner shows a list of all available endpoints, here you can edit, disable, and delete previously configured endpoints and create new ones.

Before you Start

See our Introduction to Atlassian Java API module to learn about using the Java API documentation.


Creating your own REST endpoint can be tricky. Before starting make sure you understand what the REST API is and how to use it.

Adding a REST Endpoint

Use the following REST endpoint example to examine the different parts of the script:

import com.onresolve.scriptrunner.runner.rest.common.CustomEndpointDelegate
import groovy.json.JsonBuilder
import groovy.transform.BaseScript

import javax.ws.rs.core.MultivaluedMap
import javax.ws.rs.core.Response

@BaseScript CustomEndpointDelegate delegate 

doSomething( 
    httpMethod: "GET", groups: ["jira-administrators"] 
) { MultivaluedMap queryParams, String body -> 
    return Response.ok(new JsonBuilder([abc: 42]).toString()).build() 
}

Line 8: This line makes methods in your script recognizable as endpoints, which is required.

Line 10: The name of the REST endpoint, which forms part of the URL. In this example, it is doSomething.

Line 11: This line configures the endpoint and determines which HTTP verb to handle and what groups to allow.

Line 12: This line contains parameters that are provided to your method body.

Line 13: The body of your method, where you will return a javax.ws.rs.core.Response object.

You can add this REST endpoint to the list of configured endpoints as an inline script or by copying into a file and adding that file as a script file. To test this endpoint, type this text into your browser:


<jira_base_url>/rest/scriptrunner/latest/custom/doSomething
Notice the last part of the text is the name doSomething which corresponds with the name of the closure.

Alternatively, you could type this into the command line utility:

  • Again, notice the name doSomething in each command.

  • admin:admin corresponds to a username and password.

curl -u admin:admin <jira_base_url>/rest/scriptrunner/latest/custom/doSomething
{"abc":42}

If you are using a file, you can change the response. You may need to select the Scan button on the REST Endpoints page before calls to the endpoint return the new response. See the section on Script Root Scanning below.

Error rendering macro 'includeplus'

Hazelcast instance is not active!

On this page